Repository navigation
perf: cut api build cost where nimbus owns it - #293
Merged
Merged
Conversation
The text was parsed three times: validate, dereference and the ref-preserving copy each parsed it again. One parse now feeds dereference and the raw document; validate keeps its own because Scalar's validator rewrites a non-string info.version on the object it is handed. Empty or unparseable text now fails with "could not be parsed" instead of "produced no document to render".
The version cache keyed on one composite hash and logged nothing on a miss, so a slow build could not be told apart from a cache that never hit. Each version now keeps a small record of the input digests its last preparation hashed, and the "Prepared API pages" line names the inputs that differ, or the first build.
Staging asserted every path segment, made the directory and checked the target for each of thousands of files; now the roots and each directory are checked once and a file costs one lstat and one clone. The request-route inventory rendered every API page a second time for its searchable text although the bake had just written the same Markdown; it now reads the twin like every other page.
The virtual module inlined every Markdown and llms asset row into the server bundle, a 2.5 MB chunk on a large API. Staging now writes manifest.json beside the assets and a server build reads it once per isolate through the staged-asset reader; dev and prerendered routes keep the inlined copy.
🚀 Deploying Preview to Cloudflare 🚀Preview URL: https://feat-api-build-cost.nimbus-docs.com (commit 0f5602d)This URL reflects your latest Preview deploymentPreview Deployments by commit
|
MohamedH1998
changed the title
…e changes The shared parse now probes one $ref after dereferencing and parses the text again if a parser version resolved in place, so schema links cannot disappear silently. Staging fails with a clear error when the agent-endpoint manifest would exceed Cloudflare's 25 MiB static file limit instead of failing the deploy later. The Worker purity check allows the published manifest path it now reads by design while still rejecting the build directory.
MohamedH1998
added this pull request to stack #297
October 24, 2026 21:51
The staging error names a remedy, the rebuild reason no longer says "this version" for an API without versions, and the changeset and guides say which builds print the rebuild line and what the staged manifest is.
MohamedH1998
marked this pull request as ready for review
October 25, 2026 09:56
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Four small performance changes to the API engine, measured on the Cloudflare API site (2,974 operations). None adds config or a cache. The build's wall time does not move; the gains are structural: one fewer parse, one fewer render pass, a lighter Worker, and a log line that says why a rebuild happened.
Decision: adopt all four. First PR of a stack of four.
Changes
$refs; if a parser version ever resolves in place, the text is parsed again, so links cannot disappear silently.bundle: false, say on a version-cache miss what changed: Nimbus, an installed package, the spec, or the routes, or that nothing was cached yet. Per-component digests live in a small sidecar per version, pruned with the version.Validation
pnpm typecheck; fullnimbus-docssuite; Workers feasibility matrix on workerd.wrangler dev, rebuild reasons name the spec, the cache, or a first build; static output unchanged. Its wording findings are applied in the last commit.