chore(build): use `vite` in the `web` generator by avivkeller · Pull Request #937 · nodejs/doc-kit

avivkeller · 2026-07-23T20:30:44Z

Note: I used a bit of AI assistance with this PR to resolve some issues with Rolldown->Vite (e.g. virtual modules)

By using Vite (which uses Rolldown internally) in the web generator, we no longer need to maintain a decent amount of custom overhead, including:

Custom resolvers
Custom CSS transformer (now that we don't use one, we can import CSS from external packages.¹)

Additionally, by utilizing Vite's handling of HTML sources, we can reduce our memory by using write: true, and outputting the HTML as they generated (and removing them from memory). This doesn't have a lot of memory, but it does save a look 7-10%.

There was a reason we didn't do it earlier, IIRC it wasn't working, but I'm not 100% sure. Regardless, it works now. ↩

vercel · 2026-07-23T20:30:50Z

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

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview, Comment	Jul 23, 2026 9:37pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
nodejs-doc-kit	Ignored		Jul 23, 2026 9:37pm

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

codecov · 2026-07-23T20:31:45Z

Codecov Report

❌ Patch coverage is 98.68852% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.10%. Comparing base (6a217f0) to head (6b744b2).

Files with missing lines	Patch %	Lines
src/generators/web/utils/vite.mjs	98.55%	4 Missing and 1 partial ⚠️
src/generators/web/utils/processing.mjs	91.66%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #937      +/-   ##
==========================================
+ Coverage   84.89%   85.10%   +0.20%     
==========================================
  Files         193      192       -1     
  Lines       17512    17645     +133     
  Branches     1551     1570      +19     
==========================================
+ Hits        14867    15016     +149     
+ Misses       2639     2623      -16     
  Partials        6        6

☔ 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 · 2026-07-23T20:33:07Z

`api-links` Generator

Output

apilinks.json

Expected values to be strictly deep-equal:
+ actual - expected
... Skipped lines

  {
    'Agent.defaultMaxSockets': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L291',
    'Buffer.alloc': 'https://github.com/nodejs/node/blob/HEAD/lib/buffer.js#L435',
    'Buffer.allocUnsafe': 'https://github.com/nodejs/node/blob/HEAD/lib/buffer.js#L449',
    'Buffer.allocUnsafeSlow': 'https://github.com/nodejs/node/blob/HEAD/lib/buffer.js#L461',
...
    'agent.addRequest': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L356',
+   'agent.createConnection': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L295',
-   'agent.createConnection': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L326',
    'agent.createSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L427',
    'agent.destroy': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L660',
+   'agent.getName': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L325',
-   'agent.getName': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L484',
    'agent.keepSocketAlive': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L616',
    'agent.removeSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L555',
    'agent.reuseSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L652',
    'assert.assert': 'https://github.com/nodejs/node/blob/HEAD/lib/assert.js#L185',
    'asyncResource.asyncId': 'https://github.com/nodejs/node/blob/HEAD/lib/async_hooks.js#L243',
...
    'server.address': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2596',
+   'server.close': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L671',
+   'server.closeAllConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L681',
+   'server.closeIdleConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L693',
-   'server.close': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2729',
-   'server.closeAllConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L120',
-   'server.closeIdleConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L122',
    'server.getConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2691',
    'server.listen': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2398',
    'server.ref': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2834',
+   'server.setTimeout': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L709',
-   'server.setTimeout': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L124',
    'server.unref': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2843',
+   'server[SymbolAsyncDispose]': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L677',
-   'server[SymbolAsyncDispose]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2769',
    'server[kDeserialize]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2319',
    'server[kTransferList]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2292',
    'server[kTransfer]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2297',
+   'server[undefined]': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L716',
-   'server[undefined]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2798',
    'serverresponse._finish': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L246',
    'serverresponse._implicitHeader': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L403',
    'serverresponse.assignSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L296',
    'serverresponse.detachSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L307',
    'serverresponse.statusCode': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L269',

Performance

Metric	Base	Head	Diff
Elapsed time	1.53 s	1.30 s	-230.00 ms (-15.03%)
User CPU time	2.82 s	2.82 s	0.00 ms (0.00%)
System CPU time	350.00 ms	340.00 ms	-10.00 ms (-2.86%)
Peak resident memory	347.15 MB	354.79 MB	+7.64 MB (+2.20%)

`legacy-html` Generator

Performance

Metric	Base	Head	Diff
Elapsed time	18.06 s	19.36 s	+1.30 s (+7.20%)
User CPU time	59.20 s	60.64 s	+1.44 s (+2.43%)
System CPU time	2.71 s	2.63 s	-80.00 ms (-2.95%)
Peak resident memory	2.32 GB	2.26 GB	-59.21 MB (-2.49%)

`legacy-json` Generator

Performance

Metric	Base	Head	Diff
Elapsed time	9.04 s	8.79 s	-250.00 ms (-2.77%)
User CPU time	27.57 s	25.59 s	-1.98 s (-7.18%)
System CPU time	1.93 s	2.02 s	+90.00 ms (+4.66%)
Peak resident memory	1.64 GB	1.61 GB	-38.28 MB (-2.27%)

`llms-txt` Generator

Performance

Metric	Base	Head	Diff
Elapsed time	8.21 s	8.14 s	-70.00 ms (-0.85%)
User CPU time	24.97 s	25.72 s	+750.00 ms (+3.00%)
System CPU time	1.74 s	1.82 s	+80.00 ms (+4.60%)
Peak resident memory	1.58 GB	1.61 GB	+28.00 MB (+1.73%)

`orama-db` Generator

Output size

|-|-|-|-|

| orama-db.json | 8.90 MB | 8.90 MB | +1.34 KB (+0.01%) |

Performance

Metric	Base	Head	Diff
Elapsed time	8.66 s	9.07 s	+410.00 ms (+4.73%)
User CPU time	25.41 s	25.33 s	-80.00 ms (-0.31%)
System CPU time	1.83 s	1.38 s	-450.00 ms (-24.59%)
Peak resident memory	1.64 GB	1.64 GB	+3.78 MB (+0.23%)

`web` Generator

Output size

|-|-|-|-|

| all.html | 21.24 MB | 21.23 MB | -5.43 KB (-0.02%) |
| quic.html | 826.71 KB | 824.91 KB | -1.80 KB (-0.22%) |
| fs.html | 1.66 MB | 1.66 MB | -1.68 KB (-0.10%) |
| http.html | 815.66 KB | 814.31 KB | -1.35 KB (-0.17%) |
| webcrypto.html | 562.27 KB | 560.93 KB | -1.35 KB (-0.24%) |
| http2.html | 838.34 KB | 837.02 KB | -1.32 KB (-0.16%) |
| stream.html | 922.95 KB | 921.64 KB | -1.31 KB (-0.14%) |
| net.html | 456.11 KB | 454.80 KB | -1.30 KB (-0.29%) |
| crypto.html | 1.20 MB | 1.20 MB | -1.30 KB (-0.11%) |
| tls.html | 413.89 KB | 412.65 KB | -1.24 KB (-0.30%) |
| webstreams.html | 398.20 KB | 396.96 KB | -1.24 KB (-0.31%) |
| util.html | 735.87 KB | 734.64 KB | -1.23 KB (-0.17%) |
| documentation.html | 37.92 KB | 36.70 KB | -1.23 KB (-3.23%) |
| perf_hooks.html | 408.64 KB | 407.42 KB | -1.22 KB (-0.30%) |
| diagnostics_channel.html | 329.91 KB | 328.71 KB | -1.21 KB (-0.37%) |
| dns.html | 319.60 KB | 318.41 KB | -1.19 KB (-0.37%) |
| v8.html | 359.09 KB | 357.91 KB | -1.19 KB (-0.33%) |
| zlib.html | 377.27 KB | 376.08 KB | -1.19 KB (-0.32%) |
| dtls.html | 161.33 KB | 160.14 KB | -1.19 KB (-0.74%) |
| url.html | 364.07 KB | 362.89 KB | -1.18 KB (-0.32%) |
| test.html | 895.25 KB | 894.08 KB | -1.18 KB (-0.13%) |
| sqlite.html | 311.82 KB | 310.65 KB | -1.17 KB (-0.37%) |
| 404.html | 29.87 KB | 28.70 KB | -1.17 KB (-3.90%) |
| index.html | 40.38 KB | 39.21 KB | -1.17 KB (-2.89%) |
| ffi.html | 143.95 KB | 142.79 KB | -1.16 KB (-0.81%) |
| dgram.html | 219.13 KB | 217.97 KB | -1.15 KB (-0.53%) |
| console.html | 149.78 KB | 148.64 KB | -1.14 KB (-0.76%) |
| events.html | 478.84 KB | 477.70 KB | -1.14 KB (-0.24%) |
| os.html | 151.78 KB | 150.64 KB | -1.14 KB (-0.75%) |
| inspector.html | 179.29 KB | 178.16 KB | -1.14 KB (-0.64%) |
| worker_threads.html | 393.99 KB | 392.86 KB | -1.13 KB (-0.29%) |
| stream_iter.html | 395.33 KB | 394.20 KB | -1.13 KB (-0.29%) |
| path.html | 144.95 KB | 143.83 KB | -1.13 KB (-0.78%) |
| cluster.html | 204.11 KB | 202.99 KB | -1.13 KB (-0.55%) |
| readline.html | 264.41 KB | 263.28 KB | -1.13 KB (-0.43%) |
| tty.html | 99.21 KB | 98.09 KB | -1.12 KB (-1.13%) |
| modules.html | 185.38 KB | 184.26 KB | -1.12 KB (-0.60%) |
| globals.html | 236.60 KB | 235.48 KB | -1.12 KB (-0.47%) |
| timers.html | 139.90 KB | 138.78 KB | -1.12 KB (-0.80%) |
| errors.html | 494.97 KB | 493.85 KB | -1.12 KB (-0.23%) |
| punycode.html | 64.08 KB | 62.97 KB | -1.11 KB (-1.73%) |
| domain.html | 106.44 KB | 105.33 KB | -1.11 KB (-1.04%) |
| vfs.html | 84.79 KB | 83.68 KB | -1.11 KB (-1.31%) |
| process.html | 718.89 KB | 717.78 KB | -1.11 KB (-0.15%) |
| https.html | 154.80 KB | 153.70 KB | -1.11 KB (-0.71%) |
| querystring.html | 66.28 KB | 65.18 KB | -1.10 KB (-1.66%) |
| wasi.html | 71.59 KB | 70.49 KB | -1.10 KB (-1.54%) |
| single-executable-applications.html | 108.76 KB | 107.66 KB | -1.10 KB (-1.01%) |
| async_context.html | 191.77 KB | 190.67 KB | -1.10 KB (-0.57%) |
| vm.html | 396.10 KB | 395.00 KB | -1.10 KB (-0.28%) |
| module.html | 349.31 KB | 348.21 KB | -1.09 KB (-0.31%) |
| embedding.html | 59.30 KB | 58.21 KB | -1.09 KB (-1.84%) |
| environment_variables.html | 43.92 KB | 42.83 KB | -1.09 KB (-2.48%) |
| intl.html | 58.02 KB | 56.93 KB | -1.09 KB (-1.88%) |
| packages.html | 179.01 KB | 177.92 KB | -1.09 KB (-0.61%) |
| permissions.html | 62.73 KB | 61.64 KB | -1.09 KB (-1.74%) |
| report.html | 175.80 KB | 174.71 KB | -1.09 KB (-0.62%) |
| string_decoder.html | 56.30 KB | 55.21 KB | -1.09 KB (-1.94%) |
| synopsis.html | 42.55 KB | 41.46 KB | -1.09 KB (-2.56%) |
| typescript.html | 53.35 KB | 52.26 KB | -1.09 KB (-2.04%) |
| addons.html | 274.71 KB | 273.62 KB | -1.09 KB (-0.40%) |
| buffer.html | 955.21 KB | 954.13 KB | -1.08 KB (-0.11%) |
| deprecations.html | 517.23 KB | 516.14 KB | -1.08 KB (-0.21%) |
| tracing.html | 85.13 KB | 84.04 KB | -1.08 KB (-1.27%) |
| n-api.html | 811.88 KB | 810.80 KB | -1.08 KB (-0.13%) |
| async_hooks.html | 162.93 KB | 161.85 KB | -1.08 KB (-0.66%) |
| esm.html | 158.91 KB | 157.83 KB | -1.08 KB (-0.68%) |
| debugger.html | 100.66 KB | 99.59 KB | -1.07 KB (-1.07%) |
| repl.html | 184.01 KB | 182.94 KB | -1.07 KB (-0.58%) |
| child_process.html | 404.87 KB | 403.80 KB | -1.07 KB (-0.26%) |
| assert.html | 347.02 KB | 345.96 KB | -1.06 KB (-0.30%) |
| cli.html | 517.68 KB | 516.66 KB | -1.02 KB (-0.20%) |

Performance

Metric	Base	Head	Diff
Elapsed time	77.41 s	75.34 s	-2.07 s (-2.67%)
User CPU time	166.46 s	161.33 s	-5.13 s (-3.08%)
System CPU time	4.75 s	5.69 s	+940.00 ms (+19.79%)
Peak resident memory	5.69 GB	5.16 GB	-549.29 MB (-9.42%)

avivkeller · 2026-07-23T20:34:15Z

-635.66 MB (-10.90%)

That's a good sign

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

cursor · 2026-07-23T21:36:30Z

PR Summary

High Risk
This is a major change to the core static-site build path (bundling, SSR, asset URLs, and generator return type), with a breaking config surface (rolldown/lightningcss → vite).

Overview
Rebuilds the web generator on Vite ~8.1, replacing the custom Rolldown/LightningCSS-wasm pipeline (bundle.mjs, css.mjs, chunks.mjs, import maps, and manual HTML/JS/CSS writes).

Build flow: SSR runs through a temporary Vite SSR build whose entries export default renderers; populated HTML templates become Vite HTML entries so Vite injects hashed assets, CSS, and preloads and writes directly to output. generate now returns void instead of in-memory HTML/CSS.

Config/API: lightningcss and rolldown options are removed in favor of web.vite (UserConfig). Client/server branching uses import.meta.env.SSR instead of CLIENT/SERVER defines. The HTML template drops import maps and a fixed styles.css link; fonts move to @fontsource imports in ui/index.css.

Docs, types, and tests are updated for output-on-disk behavior, absolute asset URLs, and user Vite plugins.

^{Reviewed by Cursor Bugbot for commit 6b744b2. Bugbot is set up for automated code reviews on this repo. Configure here.}

avivkeller · 2026-07-23T21:39:06Z

Perfomance is up to 91% :-)

cursor

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 6b744b2. Configure here.}

Copilot AI review requested due to automatic review settings July 23, 2026 20:30

Copilot AI reviewed Jul 23, 2026

vercel Bot deployed to Preview – api-docs-tooling July 23, 2026 20:31 View deployment

Copilot AI review requested due to automatic review settings July 23, 2026 21:07

Copilot AI reviewed Jul 23, 2026

vercel Bot deployed to Preview – api-docs-tooling July 23, 2026 21:08 View deployment

avivkeller changed the title ~~[wip] vite~~ chore(build): use vite in the web generator Jul 23, 2026

feat(web): use vite for generation

6b744b2

avivkeller force-pushed the vite branch from c3931b4 to 6b744b2 Compare July 23, 2026 21:36

Copilot AI review requested due to automatic review settings July 23, 2026 21:36

Copilot AI reviewed Jul 23, 2026

avivkeller marked this pull request as ready for review July 23, 2026 21:36

avivkeller requested a review from a team as a code owner July 23, 2026 21:36

vercel Bot deployed to Preview – api-docs-tooling July 23, 2026 21:37 View deployment

cursor Bot reviewed Jul 23, 2026

View reviewed changes

Comment thread src/generators/web/utils/vite.mjs

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

chore(build): use `vite` in the `web` generator#937

chore(build): use `vite` in the `web` generator#937
avivkeller wants to merge 1 commit into
mainfrom
vite

avivkeller commented Jul 23, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jul 23, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

codecov Bot commented Jul 23, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 23, 2026 •

edited

Loading

Uh oh!

avivkeller commented Jul 23, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

cursor Bot commented Jul 23, 2026 •

edited

Loading

Uh oh!

avivkeller commented Jul 23, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

avivkeller commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Footnotes

Uh oh!

vercel Bot commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

codecov Bot commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

api-links Generator

Output

Performance

legacy-html Generator

Performance

legacy-json Generator

Performance

llms-txt Generator

Performance

orama-db Generator

Output size

Performance

web Generator

Output size

Performance

Uh oh!

avivkeller commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

avivkeller commented Jul 23, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

avivkeller commented Jul 23, 2026 •

edited

Loading

vercel Bot commented Jul 23, 2026 •

edited

Loading

codecov Bot commented Jul 23, 2026 •

edited

Loading

github-actions Bot commented Jul 23, 2026 •

edited

Loading

`api-links` Generator

`legacy-html` Generator

`legacy-json` Generator

`llms-txt` Generator

`orama-db` Generator

`web` Generator

avivkeller commented Jul 23, 2026 •

edited

Loading

cursor Bot commented Jul 23, 2026 •

edited

Loading