Hacktoberfest 2026：維護者為十月標記出來的 issue，仍然開放、適合新手。 瀏覽 Hacktoberfest issue

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

未關閉
  • 哪裡不對？
#1,188 0 則留言 1 個 reaction 已指派 1 人 在 GitHub 檢視

維護者通常 3 天內回覆

@avivkeller 已經在處理了。

開始於 2026年10月26日。

評估

這個 Issue 還沒有評估資料。

描述

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

主要語言
JavaScript
星號
70
分支
79
平均合併
2 天 12 小時
30 天內合併 PR
52

環境準備

從這裡開始

  1. 先讀完整個 Issue，再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫，在一個分支上完成修改。
  4. 送出 Pull Request，並在描述裡引用這個 Issue 編號。

nodejs/doc-kit 的其他 Issue

查看 nodejs/doc-kit 的全部 Issue

相似的 Issue

更多 JavaScript Issue

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。