Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

cli: add a `dev` command with in-memory builds and HMR

Abierto
  • ¿Algo no está bien?
#1,188 0 comentarios 1 reacción 1 asignado Ver en GitHub

Los mantenedores suelen responder en 3 días

@avivkeller ya está trabajando en esto.

Desde el 26/10/2026.

Evaluación

Este issue todavía no se ha evaluado.

Descripción

CLI Web Generator

Hey folks 👋

Summary

Now that doc-kit preview is on its way (#1082), the natural follow-up is a doc-kit dev command: a long-running process that keeps the whole pipeline in memory, serves pages through Vite's dev server, and on every change redoes only the work that change affects, pushing the result straight to the browser.

Today the loop for anyone editing docs (or working on doc-kit itself) is: change a file, run a full generate, serve the output, refresh. node --run watch just restarts the whole CLI. On the Node.js API docs, a full web build takes roughly 7-9s with 4 threads and around 25s with one, and almost all of that is spent on pages you didn't touch:

Step (Node.js docs, -p 4) Time
Parse Markdown (ast, metadata) ~2s
jsx-ast (every page) ~3.5s
Bundle the site (Vite, rolldown, lightningcss) ~1s
Render 782 pages ~1.5-2s

Editing one Markdown file should only re-parse that file, rebuild its page, and render it when the browser asks for it.

Proposal

1. Output that isn't necessarily a folder

Every generator writes its own files with join(config.output, ...), through @doc-kit/core/utils/file.mjs or node:fs directly (15 generators), and html also writes its page programs to os.tmpdir() and runs vite build with write: true. A dev command can't keep things in memory until that goes through one place.

The idea is an output abstraction the generators write through, with the destination picked by --output:

// instead of writeFile(join(config.output, 'sitemap.xml'), sitemap)
await output.write('sitemap.xml', sitemap);
  • a folder, as today (-o out/)
  • memory, for dev (and for tests, which today write to temp folders)
  • a stream or callback, for programmatic use (e.g. piping pages somewhere, or an upload target)

Several generators already skip writing when output isn't set and just return their result, so this mostly generalizes what's there.

2. dev reuses the preview server

dev would use the same server as #1082 (createStaticServer), serving from the in-memory output instead of a folder, with Vite's middleware in front of it for client assets and HMR:

doc-kit dev -i 'doc/api/*.md' --port 5173
3. A development build mode

dev doesn't need production output, so it can skip the expensive parts:

  • Vite's dev server instead of vite build for the client (server.middlewareMode, appType: 'custom'), so CSS and island components get real HMR.
  • Server components loaded through Vite's Environment API (server.environments.ssr.runner.import(), the replacement for ssrLoadModule) instead of bundling the component library up front.
  • No minification (JS, CSS through lightningcss, or --minify HTML), with source maps on.
  • Pages rendered on request, the way VitePress and hugo server work, instead of rendering all 782 up front. This is probably the single biggest win.
  • Aggregates (all.html, the search index, sitemap.xml, llms.txt) built lazily, or skipped by default.
4. HMR that knows what changed

Watch the inputs and map each change to the work it invalidates:

What changed What gets redone
One Markdown file That file's ast and metadata, its page and section pages in jsx-ast, and its rendered page. If its headings changed, every page's sidebar is stale too, so rendered pages get invalidated (and re-rendered on request).
A component or CSS Vite's HMR for the client; server components get invalidated so pages re-render (Vite's SSR guide shows the full-reload pattern for this).
Config, index.md, the changelog or the type map A full rebuild, still in memory.

The browser gets a reload of the page it's on through Vite's HMR channel, which can get finer-grained later.

Open questions

  • Per-file results. Generators stream whole collections today (metadata returns one array), and caching.mjs evicts each result after its last consumer, because a run ends. dev needs results kept and invalidated per input file, which is the same groundwork as incremental builds (#1010 and #1189).
  • Workers. Keep a warm pool in dev instead of ending idle workers after 250ms?
  • Which targets. Starting with web seems right; legacy-html could follow once the output abstraction exists.
  • Determinism. Comparing a rebuilt page with what's in memory works best once outputs are byte-identical between builds (#1183, #1184).

Acceptance criteria

  • doc-kit dev serves the site without writing build output to disk.
  • Editing one Markdown file updates the open page without a full rebuild.
  • Editing a component or stylesheet updates the page through HMR.
  • generate's output stays exactly the same.

References

Lenguaje dominante
JavaScript
Estrellas
70
Forks
75
Merge medio
2 d 11 h
PR fusionados (30 d)
50

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de nodejs/doc-kit

Todos los issues de nodejs/doc-kit

Issues similares

Más issues de JavaScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.