Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

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

Đang mở
  • Có gì không ổn?
#1,188 0 bình luận 1 reaction 1 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 3 ngày

@avivkeller đang làm issue này rồi.

Từ ngày 26/10/2026.

Đánh giá

Issue này chưa được đánh giá.

Mô tả

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

Ngôn ngữ chính
JavaScript
Star
70
Fork
75
Merge trung bình
2 ngày 11 giờ
Pull request đã merge (30 ngày)
50

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của nodejs/doc-kit

Tất cả issue của nodejs/doc-kit

Issue tương tự

Thêm issue về JavaScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.