Skip to content

feat: add preview command - #1082

Open
btea wants to merge 4 commits into
nodejs:mainfrom
btea:feat/add-preview-script
Open

btea wants to merge 4 commits into
nodejs:mainfrom
btea:feat/add-preview-script

Conversation

@btea

@btea btea commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

Description

Add a unified startup preview script to facilitate quick previewing and verification of changes on the page after modifying the code logic.

Validation

Related Issues

Check List

  • I have read the Contributing Guidelines and made commit messages that follow the guideline.
  • I have run node --run test and all tests passed.
  • I have check code formatting with node --run format:check & node --run lint.
  • I've covered new added functionality with unit tests if necessary.

@btea
btea requested a review from a team as a code owner September 4, 2026 05:07
@vercel

vercel Bot commented Sep 4, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
api-docs-tooling Ready Ready Preview Oct 26, 2026 2:14pm UTC

Request Review

@codecov

codecov Bot commented Sep 4, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 58.18182% with 138 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.18%. Comparing base (560c042) to head (c16d218).
⚠️ Report is 7 commits behind head on main.

Files with missing lines Patch % Lines
packages/cli/bin/commands/preview.mjs 0.00% 84 Missing ⚠️
packages/cli/bin/commands/generate.mjs 0.00% 37 Missing ⚠️
packages/cli/src/serve.mjs 88.63% 15 Missing ⚠️
packages/cli/bin/commands/index.mjs 0.00% 2 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #1082      +/-   ##
==========================================
- Coverage   93.44%   93.18%   -0.27%     
==========================================
  Files         278      281       +3     
  Lines       27815    28105     +290     
  Branches     2789     2813      +24     
==========================================
+ Hits        25993    26189     +196     
- Misses       1800     1894      +94     
  Partials       22       22              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@github-actions

github-actions Bot commented Sep 4, 2026 •

Copy link
Copy Markdown
Contributor

api-links Generator

Performance estimate (single CI run)

  • Generation time: 18.5% slower (650.00 ms → 770.00 ms)
  • Peak memory: 0.4% higher (302.18 MB → 303.46 MB)

json Generator

Performance estimate (single CI run)

  • Generation time: 40.8% slower (7.48 s → 10.53 s)
  • Peak memory: 4.4% lower (1.21 GB → 1.15 GB)

legacy-html Generator

Performance estimate (single CI run)

  • Generation time: 11.7% slower (14.67 s → 16.38 s)
  • Peak memory: 4.8% lower (1.84 GB → 1.75 GB)

legacy-json Generator

Performance estimate (single CI run)

  • Generation time: 3.1% faster (5.82 s → 5.64 s)
  • Peak memory: 3.2% lower (1.26 GB → 1.22 GB)

llms-txt Generator

Performance estimate (single CI run)

  • Generation time: 16.2% slower (7.57 s → 8.80 s)
  • Peak memory: 6.7% lower (1.14 GB → 1.06 GB)

orama-db Generator

Output size: 1 file changed · net -2.00 B

File size details
File Main PR Change
orama-db.json 29.15 MB 29.15 MB -2.00 B (-0.0%)

Performance estimate (single CI run)

  • Generation time: 15.6% slower (5.65 s → 6.53 s)
  • Peak memory: 4.1% lower (1.33 GB → 1.28 GB)

web Generator

Output size: 62 files changed · net +173.00 B

File size details
File Main PR Change
assets/SearchBox-DjNnuz7W.js 84.67 KB — -84.67 KB (-100.0%)
assets/SearchBox-DD9L4y_U.js — 84.67 KB +84.67 KB
assets/dist-DruvUqXN.js 30.42 KB — -30.42 KB (-100.0%)
assets/dist-7Sv3Eu0L.js — 30.42 KB +30.42 KB
assets/SideBar-DaKBoTPQ.js 25.62 KB — -25.62 KB (-100.0%)
assets/SideBar-Brrk92eF.js — 25.62 KB +25.62 KB
assets/client-BY1cXtbt.js — 25.08 KB +25.08 KB
assets/client-DxC3O6Ca.js 24.91 KB — -24.91 KB (-100.0%)
assets/Combination-d5oRXla-.js 16.11 KB — -16.11 KB (-100.0%)
assets/Combination-C6mYSeMI.js — 16.11 KB +16.11 KB
assets/ThemeToggle-DVZdvZ7l.js 13.65 KB — -13.65 KB (-100.0%)
assets/ThemeToggle-t7UMm7iR.js — 13.65 KB +13.65 KB
assets/dist-DVEbYasF.js 10.20 KB — -10.20 KB (-100.0%)
assets/dist-BiOceZL-.js — 10.20 KB +10.20 KB
assets/Layout-C5yPmBoc.js 10.13 KB — -10.13 KB (-100.0%)
assets/Layout-DXy0PTpC.js — 10.13 KB +10.13 KB
assets/compat-ByVaDh64.js 10.13 KB — -10.13 KB (-100.0%)
assets/compat-BGVxnT5A.js — 10.13 KB +10.13 KB
assets/Tooltip-C41LEB8U.js 7.93 KB — -7.93 KB (-100.0%)
assets/Tooltip-D0_5WcN-.js — 7.93 KB +7.93 KB
assets/dist-DNbUuC3x.js 6.99 KB — -6.99 KB (-100.0%)
assets/dist-B_8yU3XK.js — 6.99 KB +6.99 KB
assets/jsx-runtime-CW012A50.js 5.67 KB — -5.67 KB (-100.0%)
assets/jsx-runtime-CWJMV0zg.js — 5.67 KB +5.67 KB
assets/dist-cDFsq_2f.js 3.93 KB — -3.93 KB (-100.0%)
assets/dist-mb3JM3jT.js — 3.93 KB +3.93 KB
assets/CodeTabs-DT17uorw.js 3.89 KB — -3.89 KB (-100.0%)
assets/CodeTabs-CPzzUAfT.js — 3.89 KB +3.89 KB
assets/CodeBox-BNILFdqT.js 3.44 KB — -3.44 KB (-100.0%)
assets/CodeBox-UjtYavEZ.js — 3.44 KB +3.44 KB
assets/hooks.module-BbOQEtt2.js 3.40 KB — -3.40 KB (-100.0%)
assets/hooks.module-CFIEcDZS.js — 3.40 KB +3.40 KB
assets/FunctionSignature-BQoQjJ6P.js 2.28 KB — -2.28 KB (-100.0%)
assets/FunctionSignature-Rfd1uwFe.js — 2.28 KB +2.28 KB
assets/Banner-Zf4myBWm.js 2.13 KB — -2.13 KB (-100.0%)
assets/Banner-C5QQ94Xt.js — 2.13 KB +2.13 KB
assets/ChangeHistory-C3DUcRCX.js 1.77 KB — -1.77 KB (-100.0%)
assets/ChangeHistory-D9LG4HXo.js — 1.77 KB +1.77 KB
assets/DataTag-CTUSGgLj.js 856.00 B — -856.00 B (-100.0%)
assets/DataTag-DtiaU1SZ.js — 856.00 B +856.00 B
assets/DocumentationIndex-D_jFywVL.js 833.00 B — -833.00 B (-100.0%)
assets/DocumentationIndex-B2JfRHAn.js — 833.00 B +833.00 B
assets/ArrowUpRightIcon-BSpTwAaB.js 618.00 B — -618.00 B (-100.0%)
assets/ArrowUpRightIcon-Bbb8DgHe.js — 618.00 B +618.00 B
assets/Badge-CZF-RiB7.js 616.00 B — -616.00 B (-100.0%)
assets/Badge-C-ltoqbN.js — 616.00 B +616.00 B
assets/AlertBox-BNnsWt2b.js 591.00 B — -591.00 B (-100.0%)
assets/AlertBox-3_Yfvgqh.js — 591.00 B +591.00 B
assets/CodeBracketIcon-TvXI-m3T.js 512.00 B — -512.00 B (-100.0%)
assets/CodeBracketIcon-C36OD0aC.js — 512.00 B +512.00 B
assets/dist-D1kGHM6c.js 477.00 B — -477.00 B (-100.0%)
assets/dist-Dk9IlaWb.js — 477.00 B +477.00 B
assets/ChevronDownIcon-BOnMJQ3A.js 468.00 B — -468.00 B (-100.0%)
assets/ChevronDownIcon-Do5H2e5N.js — 468.00 B +468.00 B
assets/renderLabel-CdEZo9LC.js 447.00 B — -447.00 B (-100.0%)
assets/renderLabel-B4Wm-j6_.js — 447.00 B +447.00 B
assets/Blockquote-C7yOM0SI.js 167.00 B — -167.00 B (-100.0%)
assets/Blockquote-DPf4tr3s.js — 167.00 B +167.00 B
assets/useRemoteConfig-DRPTLZY3.js 151.00 B — -151.00 B (-100.0%)
assets/useRemoteConfig-BD0WscbS.js — 151.00 B +151.00 B
assets/withIsland-C7ctRfG5.js 105.00 B — -105.00 B (-100.0%)
assets/withIsland-o2Rd4XD_.js — 105.00 B +105.00 B

Performance estimate (single CI run)

  • Generation time: 5.2% faster (24.88 s → 23.59 s)
  • Peak memory: 0.8% higher (2.04 GB → 2.06 GB)

Comment thread scripts/preview.mjs Outdated

@bmuenzenmeyer bmuenzenmeyer left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've come around to this after observing a mentee interact with this repository. There is a lot of intimidating work to get all this to work together, and for the unfamiliar, it's a lot.

Comment thread scripts/preview.mjs Outdated

@ovflowd ovflowd left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO our dev command/preview command should still follow/support doc-kit args (Supplying input folder, supplying generators... It shouldn't be locked for Node.js it should be agnostic) since we want to make a generic preview/dev command for doc-kit itself instead of bounding it to Node.js

So our dev/preview command IMO shouldn't be scripts (scripts) but be commands part of doc-kit CLI

(We should avoid using 3rd party NPM packages, http:serve is enough)

@btea

btea commented Oct 25, 2026

Copy link
Copy Markdown
Contributor Author

Makes sense — a generic preview command in the doc-kit CLI beats a Node.js-bound script. Before I rework the PR, two quick questions:

  1. Should doc-kit preview take the same options as generate (-i,-t, -o, ...) plus --port, building before serving? Or just serve an existing output directory and leave building to generate?
  2. Is dev (watch mode) in scope here, or a follow-up? I'd prefer a follow-up to keep this PR small.

Either way: serving via node:http, no new dependencies, and I'll drop scripts/preview.mjs.

@bmuenzenmeyer

Copy link
Copy Markdown
Contributor

my opinions

  • Should doc-kit preview take the same options as generate (-i,-t, -o, ...) plus --port, building before serving? Or just serve an existing output directory and leave building to generate?

I like the idea of it attempting to build at the presence of any flag besides --port - that gives flexibility in both cases.

  • Is dev (watch mode) in scope here, or a follow-up? I'd prefer a follow-up to keep this PR small.

follow up

@btea btea changed the title feat: add preview:docs & preview:node scripts feat: add preview command Oct 26, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: make it clear on docs that this is NOT production grade and meant to be used for testing.

Comment thread packages/cli/bin/commands/preview.mjs Outdated
const server = await serve(output, { port: opts.port });

logger.info(
`Serving ${output} at http://localhost:${server.address().port}/ ` +

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: We should be able to also pass the host parameter so you can serve on localhost, 0.0.0.0 or whatever you want IMO


const { runGenerators } = createGenerator();

const DEFAULT_OUTPUT = './out';

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this already defined somewhere? I feel that this command can't really run without an output flag being passed... Is it correct to assume the default should be "out" and if that's the case, then our generator command also should have a default out, no?

cc @avivkeller ?

@avivkeller

Copy link
Copy Markdown
Member

Will review today!

This branch was successfully deployed

1 active deployment
Preview – api-docs-tooling — c16d2184 Deployed Oct 26, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants