Three production workflows. Two maintained source models. The interactive React parts stay.
Vercel’s AI SDK documentation, faithfully migrated to Nift composition around retained framework islands. We preserve the publication first, profile the expensive work, and compare complete production pipelines.
An independent Nift Labs experiment. Not endorsed by Vercel. No Nift core or migration templates were changed.
01 / architectures
Name the three workflows.
The repo names describe maintained source models. Neither Nift repository is the upstream AI SDK application.
UPSTREAM
Vercel AI SDK docs Next.js / Geistdocs
Original authored content, version synchronization, Fumadocs and the Next production application.
Maintained Markdown/MDX/frontmatter and structured/versioned sources. Downloads, search and LLM references derive from that authority.
Authored source + local pinned versions
Bounded renderer → transient HTML
Nift composition + retained islands
Publication + derived projections
NIFT / RENDERED-SOURCE
Nift ai-sdk-agent (rendered-source)
Maintained HTML, metadata/navigation and coordinated reference projections. No routine Markdown/MDX content compiler.
HTML + maintained projections
Bounded island SSR refresh
Nift composition + retained islands
Publication + search/runtime assets
Same accepted publication. Different maintenance contracts.
These are complete orchestrated publication timings, not native Nift @markup performance. The compatibility layer implements the pinned corpus’s required behavior, not a general Next.js replacement.
02 / parity
Parity comes before the bars.
The migration acceptance target includes retrieval, interactive behavior and publication correctness.
1,674HTML routes
1,386primary documents
259recipe aliases
29ancillary / home pages
1,386Markdown endpoints
506redirect patterns
FRESH-CLONE ACCEPTANCE3,219 files. Every accepted byte.
All publication/runtime files in each optimized migration match that project’s accepted fresh-clone output. This is not a claim that Next’s build-artifact inventory has the same file count.
Content, retrieval and route lifecycle
Nine v5/v6/v7 document/provider/cookbook families retain content, headings/anchors, metadata, version switching, local links and search. All Markdown endpoints match frozen bytes; seven discovery outputs, sitemap/robots and OG fixtures are separately checked.
Incremental publications equal forced recomputation. Add/rename/delete retire stale HTML and Markdown together. Missing or corrupt generated products recover correctly.
72 browser states per migration
Twelve representative docs/providers/cookbook/home paths, desktop/mobile and light/dark/system. System resolved light on this host. Optimization repeats 144 migration states against frozen upstream observations; the initial campaign covered 216 states across all three implementations.
Checks cover content, geometry, style, navigation, TOC, title and broken images. No universal pixel-identity claim: animation pixels and generated React IDs are outside equality.
The link/CSS audit retains 21 inherited broken links and finds zero new failures. OG cards remain request-driven runtime output, using maintained fonts/background and metadata; normal builds do not generate a corpus of social cards.
03 / islands
Static where possible. React where useful.
Nift composition does not imply vanilla-only output. The migration retains the interactive parts rather than flattening them.
Generation/loading demos, object generation, nested weather, prompts, media/playback, provider/model selection, recipes, tabs/copy, version switching, mobile navigation and search remain interactive.
React islands hydrate around opaque static HTML. The publication does not carry a Next application runtime. Simple content controls use lightweight browser code where appropriate.
Build products have owners
Actual esbuild dependency graphs govern independently cached client, SSR, shared chrome and runtime products. Unrelated content edits preserve island bundles; source/import/toolchain changes invalidate them.
983 mounts in 1,415 content/ancillary sources pass independent host-boundary checks. The content registry is still one eager entry across 16 island families: seven emitted outputs, 1,131,411 bytes. Shared chrome emits approximately 2,035,693 bytes.
Emitted output bytes are not per-page download sizes; each family is not a separate bundle. Deterministic local AI/chat/feedback success/error fixtures verify UI and transport behavior, not live production AI, feedback or analytics. Registry splitting and dependency duplication remain future profiling targets.
04 / benchmarks
Measure the whole publication.
Preparation, framework work, Nift composition, references, search and runtime/asset publication remain inside each workflow’s command.
Warm full publication
Complete production command · five serialized samples · median and range
0200400 s
Upstream Next.js/Geistdocs337.34 s
282.84–389.32 s · five runs
Nift ai-sdk (authored-source)83.16 s
71.05–96.46 s · five runs
Nift ai-sdk-agent (rendered-source)37.96 s
26.95–41.87 s · five runs
Fresh application state
Generated application caches/products reset; maintained inputs, packages and OS caches remain.
0200400 s
Upstream Next.js/Geistdocs306.03 s
287.49–340.79 s · five runs
Nift ai-sdk (authored-source)68.87 s
67.46–89.47 s · five runs
Nift ai-sdk-agent (rendered-source)28.09 s
26.71–35.85 s · five runs
Unchanged production command
Upstream still executes a production Next build. This is not a no-op or HMR test.
0200400 s
Upstream Next.js/Geistdocs264.93 s
257.26–304.79 s · five runs
Nift ai-sdk (authored-source)12.87 s
11.89–18.65 s · five runs
Nift ai-sdk-agent (rendered-source)8.43 s
6.28–11.56 s · five runs
Complete publication · median seconds, all five-run min–max ranges
Workflow
Warm full
Fresh application
Unchanged command
Upstream Next.js/Geistdocs
337.34s282.84–389.32s
306.03s287.49–340.79s
264.93s257.26–304.79s
Nift ai-sdk (authored-source)
83.16s71.05–96.46s
68.87s67.46–89.47s
12.87s11.89–18.65s
Nift ai-sdk-agent (rendered-source)
37.96s26.95–41.87s
28.09s26.71–35.85s
8.43s6.28–11.56s
Production publication, not the Next editing loop.
Upstream’s unchanged command still performs a production Next build. This is not a Next dev-server/HMR comparison. Fresh-state medians happen to be lower than warm-full medians here, with overlapping ranges; this does not establish a causal cold-state speed advantage.
05 / iteration
Make the changed-input costs visible.
Iteration peak memory / RSS
Memory for changed-input production publications, separate from full-build memory and elapsed time. Linear bars start at zero; exact values are shown in MiB.
Maximum individual process/phase RSS; sampled tree sums remain separate in the tables
0700 MiB
body-1
Nift authored600.2 MiB
Nift rendered513.6 MiB
body-100
Nift authored694.5 MiB
Nift rendered512.8 MiB
shared-layout
Nift authored504.2 MiB
Nift rendered519.6 MiB
navigation-order
Nift authored519.5 MiB
Nift rendered458.4 MiB
island-source
Nift authored696.4 MiB
Nift rendered288.4 MiB
route-rename
Nift authored595.1 MiB
Nift rendered515.0 MiB
Original unchanged: five-sample median [min–max]. Upstream changed inputs: original single observations. Migration changed inputs: supplemental single observations on the same active NUC, pinned accepted implementation/protocol; accepted timing values are retained separately, not paired as one original cohort. Full case tables and evidence below retain the other scopes and workloads.
These are complete production publications after controlled edits. Editing and coordination labor are outside elapsed build time.
ONE BODY / NIFT AUTHORED13.19s
ONE BODY / NIFT RENDERED7.83s
One/ten-page edits in the scoped rendered pipeline compose one/ten HTML files. Search, metadata scans and shared publication still impose fixed costs.
Every Nift incremental output equals forced recomputation. Upstream rows are full production rebuilds, not Next HMR/dev-server timings. These numbers do not measure which development server offers the better live editing experience.
Controlled input cases · one production-publication observation per workflow/case, not five-sample medians
Changed input
Upstream Next.js/Geistdocs
Nift ai-sdk (authored-source)
Nift ai-sdk-agent (rendered-source)
1 document body
267.89s
13.19s
7.83s
10 document bodies
299.09s
14.61s
7.94s
100 document bodies
317.16s
20.95s
8.28s
Metadata update / remove
321.72s
15.56s
10.50s
Shared layout
326.63s
20.18s
15.15s
Navigation order
333.14s
15.99s
9.84s
Historical version
304.79s
14.24s
7.48s
Provider / reference
266.53s
16.34s
8.68s
Redirect
271.14s
12.23s
5.90s
Island source
259.37s
19.31s
11.77s
Route add
256.71s
21.32s
11.92s
Route rename
231.23s
24.36s
11.06s
Route delete
248.95s
21.71s
10.63s
Rendered-source body edits coordinate HTML, search metadata, Markdown downloads and LLM references. Metadata also coordinates navigation/sitemap; historical/provider rows use the complete coordinated cases, not faster HTML-only probes. Each upstream case uses an isolated pinned warm application state; rename/delete start with the prior fixture already published. Historical v5 mutates a local cached source fixture, not acquisition of a new release. Maintained inputs are restored.
Iteration memory / peak RSS
Incremental memory matters alongside elapsed time: a smaller affected build can leave more headroom for concurrent builds, CI jobs and agents on constrained machines. Shared changes and retained worker pools can still use substantial memory; an incremental build is not guaranteed to have a lower peak than a full build. Actual concurrency and total workflow productivity were not benchmarked.
Individual = GNU maximum individual process/phase RSS, not aggregate simultaneous memory. Sampled sum = ~50ms live descendant resident-page sum, shared pages can be double-counted, short peaks missed; not PSS. Original unchanged: five-sample median [min–max]. Upstream changed inputs: original single observations. Migration changed inputs: supplemental single observations on the same active NUC, pinned accepted implementation/protocol; accepted timing values are retained separately, not paired as one original cohort.
Parity first → profile → remove redundant work → revalidate → benchmark.
INITIAL / SINGLE DIAGNOSTICS
140.712s authored 91.409s rendered
Faithful, but expensive. Authored MDX compatibility/SSR took 89.101s; Markdown downloads 24.902s. Whole-DOM rendered island refresh took 62.036s.
OPTIMIZED / SINGLE DIAGNOSTICS
53.642s authored 25.673s rendered
Bounded workers and retained reuse; lexical island host spans and batched SSR. These diagnostic runs are not the final five-sample production medians of 83.16s and 37.96s.
Reuse the work that is actually shared
Four bounded workers reuse content-addressed compiled bodies: 201 compilations are reused within 1,386 documents. Metadata, compiler/body and renderer keys are distinct. Version-menu props retain only relevant ancestors/fallback; 5,022 mapping checks match the complete original resolver.
Search is version-scoped, Markdown projections source-scoped and discovery depends on actual projection bytes. Generated products validate input graphs and output hashes.
Keep the rejected experiment
Retaining every unique Shiki HAST/compiled file made things worse: MDX rose to 108.15s and maximum individual process/phase RSS to about 2.49 GiB. That broad cache was rejected.
The accepted design keeps reused bodies only until their last use, with a bounded repeated-input Shiki cache. Rendered island refresh replaces only host interiors rather than reparsing whole documents.
Single diagnostic observations and final campaign medians are different evidence classes. They are not interchangeable optimization percentages. The report and raw history retain both, including failed/interrupted benchmark preparation with no accepted samples.
07 / components
Authored source earns its extra work.
The five warm-full authored component medians explain the source-model difference more precisely than “Markdown is slower.”
44.17sMDX compatibility and server rendering
10.95sMarkdown projection conversion
12.41sshared page UI preparation
6.32ssearch indexing
3.17sNift composition
The authored pipeline derives more representations: MDX/SSR, Markdown downloads, reference projections, search, navigation, shared UI and publication. The rendered pipeline maintains closer-to-final HTML and references, while still doing island refresh, shared UI, search and publication.
The composition phase includes preparation and the Nift CLI. Bare Nift is only one part of the complete pipeline; these are not native Markdown-renderer timings.
Upstream Next.js/Geistdocs · all sequential component medians
Seconds · five-sample phase medians; their medians need not sum to the complete-pipeline median
Phase
Warm full
Fresh application
Unchanged command
content-version-synchronization
0.771s
0.680s
0.681s
fumadocs-mdx-generation
0.389s
0.331s
0.314s
next-production-build
334.457s
303.585s
262.689s
Nift ai-sdk (authored-source) · all sequential component medians
Seconds · five-sample phase medians; their medians need not sum to the complete-pipeline median
Phase
Warm full
Fresh application
Unchanged command
authored source synchronization
1.200s
1.279s
0.937s
content island compilation
1.229s
0.904s
0.205s
shared UI compilation
1.190s
0.977s
0.164s
MDX compatibility and server rendering
44.172s
37.488s
3.518s
content navigation
0.654s
0.421s
0.407s
ancillary authored pages
1.128s
0.853s
0.821s
Markdown projection conversion
10.952s
9.323s
0.910s
discovery projections
0.814s
0.773s
0.477s
shared page UI preparation
12.411s
10.964s
3.476s
Nift composition
3.172s
2.290s
0.835s
search indexing
6.319s
5.366s
0.470s
runtime handler compilation
0.315s
0.221s
0.075s
reference and runtime publication
1.021s
0.851s
0.689s
Nift ai-sdk-agent (rendered-source) · all sequential component medians
Seconds · five-sample phase medians; their medians need not sum to the complete-pipeline median
Phase
Warm full
Fresh application
Unchanged command
content island compilation
1.305s
0.882s
0.191s
shared UI compilation
1.236s
0.881s
0.143s
maintained HTML island preparation
5.144s
4.679s
0.962s
ancillary HTML island preparation
0.335s
0.337s
0.049s
shared page UI preparation
16.449s
12.284s
4.169s
Nift composition
3.393s
2.552s
1.582s
search indexing
6.715s
5.443s
0.393s
runtime handler compilation
0.320s
0.207s
0.101s
reference and runtime publication
1.124s
0.930s
0.824s
Upstream’s Fumadocs CLI generates source/index modules; actual MDX compilation and highlighting also run inside Next’s production-build stage. Shiki nests inside transforms; concurrent worker task sums can exceed wall time. Do not add nested or concurrent counters to sequential elapsed phases. The initial uninstrumented I/O counter of zero is not evidence of zero filesystem work.
08 / memory
Name the memory scope.
The gap is substantial. The measurement definitions stay attached to it.
Warm-full individual process / phase RSS
GNU maximum RSS · maximum measured individual process/phase · five-sample medians
01500030000 MiB
Upstream Next.js/Geistdocs23,671.5 MiB
19,978.9–28,277.9 MiB · five runs
Nift ai-sdk (authored-source)901.8 MiB
887.4–944.4 MiB · five runs
Nift ai-sdk-agent (rendered-source)758.9 MiB
757.4–759.4 MiB · five runs
Individual RSS is not the worker pool’s total footprint.
A supplemental nominal 50 ms sampler sums live descendant RSS, with scan overhead. Shared pages may be counted more than once; short peaks may be missed. This is approximate and not exact aggregate resident memory or an OS peak.
Warm-full medians · separate memory scopes · five runs
Workflow
Individual process/phase
Sampled descendant RSS sum
Upstream Next.js/Geistdocs
23,671.5 MiB19,978.9–28,277.9
29,277.7 MiB27,016.7–33,514.6
Nift ai-sdk (authored-source)
901.8 MiB887.4–944.4
4,380.7 MiB4,372.5–4,518.0
Nift ai-sdk-agent (rendered-source)
758.9 MiB757.4–759.4
777.4 MiB775.4–777.9
For the authored worker pool, the sampled warm median is 4,380.7 MiB, despite a 901.8 MiB maximum individual-process median. Both scopes matter. The A10 reports retain all fresh/unchanged memory distributions as well.
09 / maintenance
Faster is not automatically preferable.
Choose the maintained source contract, then judge its publication pipeline.
NIFT ai-sdk (AUTHORED-SOURCE)
One authority. Derived projections.
Markdown/MDX/frontmatter and structured versions remain authoritative, readable and easier to review. Downloads, search and LLM references derive from source; retained islands have independent ownership.
Cost: transformation work, a bounded compatibility layer and internal Geistdocs/Fumadocs coupling. Four pinned internal Geistdocs UI modules and one private Fumadocs search reader are explicit maintenance liabilities.
NIFT ai-sdk-agent (RENDERED-SOURCE)
Less transformation. More coordination.
Faster publication and no routine MDX compiler. Agents can maintain HTML directly.
Cost: edits must coordinate HTML, search data, Markdown downloads, LLM references and metadata/navigation. The benchmark excludes the effort of making those changes consistent.
Upstream remains a credible third option.
Next.js/Geistdocs also has authoritative source and stronger native framework, development and deployment integration. The production build measurements do not measure every advantage of that ecosystem.
Fonts and compiled stylesheets are maintained publication assets with explicit update workflows. Homepage statistics and model catalogs are pinned maintained snapshots, while upstream retains public npm/GitHub requests and timeout fallbacks. These architectural differences remain part of the comparison.
Remaining costs are future profiling targets
MDX/highlighting, derived reference work, shared shell SSR, corpus metadata/hash scans, per-version search export and publication copying remain real costs. Navigation legitimately fans out over its tree. Registry splitting, dependency duplication, startup/scan overhead, search granularity and concurrent-memory reductions deserve later investigation. They do not reopen this accepted experiment.
10 / opinion
An explicit three-way judgement.
Codex assessed Upstream Next.js/Geistdocs, Nift authored-source and Nift rendered-source—not the repo name in isolation.
AGENTS IMPLEMENT / HUMANS DIRECT
Preferred: Nift ai-sdk (authored-source)
One authoritative source, lower coordination burden, independently retained islands and much lower measured publication time/memory than upstream. The additional transformation cost is acceptable for consistency.
HUMANS + AGENTS BOTH EDIT
Preferred: Nift ai-sdk (authored-source)
Markdown/MDX/frontmatter and structured sources are easier to edit and review. The rendered-source speed does not outweigh the stronger source-of-truth model.
REMOVE MIGRATION EFFORT + INCUMBENCY
Codex still prefers Nift ai-sdk (authored-source) in both maintenance scenarios.
This accepts the bounded adapter burden for the demonstrated publication architecture. Upstream is credible when native development/deployment integration takes priority; the experiment does not fully measure that tradeoff. Official adoption still requires a deployment/backend pilot.
11 / official
Worth evaluating. Not a migration decree.
The evidence justifies Vercel evaluating a migration from the current Next.js/Geistdocs AI SDK docs application to Nift composition with retained React islands.
Why investigate seriously
Complete production publication is materially faster with lower measured memory, while maintaining authored content and real interactive islands. Controlled production edits, complete output coverage and fresh-clone reproduction make this an engineering result worth testing in a real deployment.
What a production pilot must resolve
Host/runtime deployment, process rollover, private API credentials, AI/chat/feedback/search integration and analytics. Local fixtures do not certify those services. Internal module coupling, maintained asset/snapshot updates and native Next tooling must enter the decision.
A serious deployment/backend evaluation, not an unconditional recommendation. Build performance alone does not establish that Vercel should migrate the official site. The external playground remains separately hosted.
12 / guidance
The islands lesson is discoverability.
Dogfooding nift init --migration did not reveal a framework prohibition.
Generated guidance already permits React, Vue, Svelte and other tools. What needed stronger visibility was island composition and explicit ownership of client/SSR products, dependencies, emitted bytes and invalidation.
Future guidance should make “the lightest faithful solution” concrete: Nift composes the publication; neighboring tooling owns useful interactive islands. It should distinguish maintained assets from derived products, authoritative versus coordinated source models, remote-service evidence, pinned versions and full/cached/fresh build scope.
These are proposals for later guidance work. No Nift core or generated migration-template source was changed during this experiment.
13 / methodology
Keep the boundaries in view.
A production benchmark is useful when readers can see exactly what it includes and excludes.
Commands + pinned inputs
Upstream: pnpm --dir apps/docs build:site, including sync, Fumadocs and Next production build. Migrations: python3 scripts/build-content.py (forced for full modes), including preparation, bundling, Nift, reference outputs, search and asset/runtime publication.
Node 24.21.0, pnpm 11.23.0, Nift 4.8.0. Upstream keeps its pinned eight-CPU Next setting; authored MDX uses four bounded workers. Six public external image responses are frozen. No private credentials or real backend submissions.
Sampling + state
Five serialized samples for each of three modes and workflows, rotating project order: 45 accepted publications. Active host; OS cache state uncontrolled. Fresh application state clears generated application caches/products, keeps maintained assets and installed packages, and is not machine cold.
Dependency installation, state-reset/archive preparation, input mutation and verification are excluded. Input-case observations are single runs, not distributions.
What is not measured
Next dev-server/HMR, source-editing/review labor, deployment transfer, host/process startup, production backend latency or private AI/feedback/analytics integration. Local deterministic fixtures establish a narrower UI/transport contract.
Preview robots keep Disallow: /; production indexing policy needs deployment configuration. Runtime changes require the deployment runtime to roll over.
Accounting + limitations
Individual process/phase RSS and approximate sampled descendant RSS sums differ. Nested Shiki/task counters are not additive. Phase medians need not sum to pipeline medians.
Next’s build/runtime artifacts and standalone public/runtime files have different transport inventories; raw file-count equality is not claimed. Coverage and output hashes are established by separate parity gates.
14 / evidence
A report you can trace back.
Both completed migration repositories remain untouched by this Labs publication. Evidence links pin the accepted report commits.
Upstream pin 3ebefff610f96892c50be48cf1838c453e2349f7. Report pins: authored 6d07d2f06a96d33deac0384514574d069cce98b7; rendered 524b1840a0a36d0dafdfbc368f52fb526951bad8. Measured implementation heads are retained in the raw sample records; these later commits add final reporting evidence.