NIFT The application survives.
TanStack Start, Router, React hydration and client navigation remain active. The application framework keeps its responsibilities.
Agora Docs / real-time systems / October 2026
Agora Docs TanStack Start + Nift
A 2,003-page documentation publication. Keep the interactive application. Rework the build around it.
Agora’s real-time communications platform has a substantial bilingual documentation portal. This experiment preserves TanStack Start, Router, React and authored MDX while changing how content and publication work move through the pipeline.
Independent engineering experiment. Public source pinned before migration. Nift core unchanged. No Agora or TanStack endorsement.
APP ⇄ BUILDCOOPERATING SYSTEMS
and client navigationNiftDependencies, composition
and publication
One application, cooperating responsibilities.
Signal schematic · not a measured waveform.
The engineering decision
Our maintenance choice:
Nift + TanStack Start
For maintaining Agora’s documentation, we would choose the Nift-assisted authored-source implementation over the original upstream build workflow.
Read the three-way maintenance judgementThe build gets substantially lighter.
The authored fresh-state observation is 199.82s / 1.89 GiB, versus two upstream production observations around 600s / 4.9 GiB. Source and cache conditions differ.
We’d maintain the authored Nift version.
Markdown/MDX remains authoritative, derived outputs stay coordinated, and document edits avoid unnecessary application compilation. This choice applies to this documentation workload.
Two upstream observations; one observation per Nift scenario. Descriptive comparisons, not matched-cache distributions. Production hosting, regional and inherited behavior qualifications remain below.
01 / parity
The publication comes first.
Performance is useful only if the reconstructed application still does its job.
2,017reference HTML paths
1,657article identities
3,100non-HTML, non-bundle reference paths
1,049matching LLM content blocks
Corpus and independent clones
The pinned upstream generator writes 2,003 documentation HTML files; aliases, fallbacks and verification files bring the complete reference HTML inventory to 2,017. Both independent GitHub clones preserve that inventory and every non-HTML, non-bundle reference path. Authored publication contains 6,859 files; the maintained-React model contains 6,862. Content-addressed bundles differ from upstream by design.
All 1,657 compiled article modules match between the models. Canonical document payload fields, Markdown download bytes, search entry content and LLM blocks reconcile with the frozen reference. Search-row and LLM-block ordering varies in upstream and is compared separately.
Actual application behavior
Representative browser checks exercise React hydration, search and client navigation/history, API controls, code tabs, FAQ filtering, themes and the mobile drawer. Chinese Start hydration, localized Orama search and client navigation pass at an explicitly local fixture origin.
These are representative behavioral and visual checks, not a claim that every route and viewport is pixel-identical. A saved dark theme triggers a React hydration mismatch in the frozen upstream output and the migration; the application recovers. The unchanged theme/root implementation and matched browser reproduction establish this as an inherited defect, not clean hydration across every theme state. Complete Chinese production publication and actual provider behavior remain separate certification gaps.
Restoration is checked, not assumed.
Warm and restored outputs retain exact non-HTML bytes. HTML agrees after comparison-only normalization of the Router’s bootstrap updatedAt fields inside its stream-barrier script. Article content and other dates are untouched; production HTML is never normalized. A real upstream highlighting variation is retained in the repeatability evidence.
02 / architecture
A different build workflow. The same framework.
The original portal uses TanStack Start/Router, React, Vite and Fumadocs. Nift takes responsibility for publication composition rather than replacing their runtime.
The project was selected to test a hybrid adoption path: substantial authored MDX, shared components, bilingual navigation, platform variants, OpenAPI references, search and machine-readable exports. Replacing all of this with a static approximation would answer a different question.
Nift agora / authored-source
Keep authored content authoritative.
- Maintained Markdown / MDX, frontmatter, includes, navigation and OpenAPI
- Independent Fumadocs compilation → cached React ESM + metadata
- Derived search, Markdown and LLM projections
- Retained Vite / TanStack application + production route SSR
- Transient HTML → Nift raw composition → publication
Generated modules and HTML are disposable. Recursive includes, image bytes/dimensions, compiler configuration, source hashes and package revisions participate in invalidation. Editorial dates retain their upstream seed and explicit maintenance workflow.
Nift agora-agent / maintained React ESM
Maintain the compiled representation.
- Maintained React ESM articles + explicit catalog/raw/processed metadata
- Derived search, Markdown and LLM projections
- Retained Vite / TanStack application + production route SSR
- Transient HTML → Nift raw composition → publication
No Markdown/MDX article compiler runs during routine publication. The maintained source is React ESM, not HTML-only: shared interactive components still run. Agents must coordinate article modules and their text/metadata representations when editing content.
Fumadocs still supplies content semantics and UI. TanStack still supplies routing and SSR, Vite still bundles the application, and React still renders and hydrates it. These measurements cover the orchestrated pipeline, not native Nift @markup throughput.
03 / measurements
Complete work, measured explicitly.
Two upstream observations and one observation per Nift scenario. These are engineering observations, not statistically established distributions.
Nift agora / authored-source
≈3× faster observed build199.82s fresh application state
1,937.1 MiB sampled peak tree RSS
Nift agora-agent / maintained React ESM
≈8.4× faster observed build71.79s fresh application state
1,343.0 MiB sampled peak tree RSS
Descriptive ratios use the midpoint of two upstream production observations (599.62s / 5,022.7 MiB). Nift values are single fresh-state observations. Cache conditions and maintained-source work differ; these are not equivalent-work compiler benchmarks.
Production / fresh-state elapsed time
Upstream production runs and Nift fresh-state runs have different cache/source conditions.
Upstream production · observation 1592.09 s
Upstream production · observation 2607.14 s
Nift maintained React ESM71.79 s
Production / fresh-state sampled tree RSS
Upstream production runs and Nift fresh-state runs have different cache/source conditions.
Upstream production · observation 14,966.6 MiB
Upstream production · observation 25,078.8 MiB
Nift maintained React ESM1,343.0 MiB
| Observation | Wall time | Sampled peak tree RSS |
|---|---|---|
| Upstream 1 | 592.09s | 4,966.6 MiB |
| Upstream 2 | 607.14s | 5,078.8 MiB |
The two upstream observations are 592.09s / 4,966.6 MiB and 607.14s / 5,078.8 MiB. Their midpoint gives descriptive ratios of approximately 3.0× authored and 8.4× maintained-React elapsed improvement, with about 61% and 73% lower sampled RSS. The midpoint is neither a median campaign nor a cache-matched benchmark. Source representations perform different work.
| Workload | Nift agora authored-source | Nift agora-agent maintained React ESM |
|---|---|---|
| Fresh application state | 199.82s1,937.1 MiB | 71.79s1,343.0 MiB |
| Warm forced publication | 43.77s750.4 MiB | 45.09s748.4 MiB |
| Unchanged | 2.37s180.6 MiB | 2.75s304.8 MiB |
| Document edit | 7.51s1,213.9 MiB | 7.24s1,125.4 MiB |
| Shared-layout edit | 49.63s979.6 MiB | 52.22s916.7 MiB |
The warm workload is not the upstream workload.
Fresh Nift state retains installed dependencies but regenerates application/content artifacts from maintained sources. Forced full publication reuses valid compiled artifacts while rendering/composing every page. Upstream production observations reused build/install state and follow the original complete production command. Clone/install time, source editing and browser inspection are excluded; OS caches are uncontrolled.
04 / iteration
Follow the changed input.
Complete-pipeline production observations for unchanged state, one document and shared layout. Each event carries its own time and memory cost.
Unchanged
Publication time
One observation per model · zero-origin linear scale
Nift maintained React ESM2.75 s
Sampled peak tree RSS
One observation per model · zero-origin linear scale
Nift maintained React ESM304.8 MiB
Document edit
Publication time
One observation per model · zero-origin linear scale
Nift maintained React ESM7.24 s
Sampled peak tree RSS
One observation per model · zero-origin linear scale
Nift maintained React ESM1,125.4 MiB
Shared-layout edit
Publication time
One observation per model · zero-origin linear scale
Nift maintained React ESM52.22 s
Sampled peak tree RSS
One observation per model · zero-origin linear scale
Nift maintained React ESM916.7 MiB
Incremental memory belongs beside incremental time.
Both models avoid application bundling for the measured prose-only document edit. They still update the necessary content/projections and render affected routes. The edit leaves editorial dates unchanged; metadata/date changes may invalidate more work. Shared CSS/layout changes rebuild the application and fan out through publication.
The authored and maintained-React edits are deliberately different source operations. Manual coordination of agent text and module edits is outside the clock. These results do not establish total editing productivity. Equivalent upstream incremental observations were not collected, so no incremental speedup over upstream is claimed.
05 / optimization
Remove repeated work before tuning Nift.
The improvement came from the combined architecture and its preparation stages.
Separate compilation and publication
Article compilation no longer depends on rebundling the entire application. Valid React ESM and metadata survive ordinary publications. Clean payload paths defer expensive worker/source imports; cached projections are reused when their inputs are unchanged.
Bound work and memory
Compiler workers keep bounded lifetimes and merge metadata deltas once. SSR uses two production workers with bounded route batches and heaps. An immutable shared route plan avoids repeated corpus-wide dependency planning in each batch.
Load only the metadata needed
Compact frontmatter heads and lazy per-document records replace eagerly retaining the full projection catalog in every SSR worker. The complete catalog still exists for exports. Server-only metadata stays out of the public tree.
Preserve correctness while caching
Asset copying checks both source and destination identity and repairs missing/corrupt outputs. Raw source hashes track edits that do not change compiled React. Retirement and restoration gates accompany incremental shortcuts.
Authored warm full87.21s → 43.77s
Maintained React warm full92.28s → 45.09s
The initial corrected and optimized captures remain separate historical checkpoints. The earlier SSR path selected development React; the optimized path explicitly uses production React. This is an implementation improvement, not equivalent renderer conditions hidden behind a single table. Initial incomplete-scope captures and a rejected agent projection integration are retained locally as rejected diagnostics.
06 / remaining costs
The remaining costs stay visible.
Neither model reached the sub-10-second aspiration; warm forced publication also remains above the 20-second milestone.
| Model | MDX compilation | Maintained content | Projections | Application | Route SSR | Nift composition |
|---|---|---|---|---|---|---|
| Nift authored-source | 132.85s | — | 18.32s | 5.25s | 40.98s | 0.56s |
| Nift maintained React ESM | — | 2.45s | 18.46s | 5.40s | 42.00s | 0.56s |
Fresh authored compilation took 132.85s; full projection work costs about 18s in both models. Production route SSR still costs around 41–42s, while Nift composition takes about 0.56s in these fresh observations. Warm forced publication is dominated by SSR; fresh and document-edit memory peaks occur in content/projection preparation. The maintained-React pipeline still pays meaningful costs despite avoiding MDX compilation.
Fixed fingerprint/planning/startup work keeps no-op publication above two seconds. Large shared changes still fan out. These are future integration/compiler/SSR profiling targets; no deeper performance project is required to explain the current result honestly.
07 / certification
A certified global corpus. A qualified deployment story.
The evidence supports the migration result, with clear boundaries on production claims.
Content and application checks
Independent clones, complete reference paths, projections, module reconciliation and restoration pass. Type checks and 101 focused tests per model passed. Representative English hydration/navigation and Chinese fixture behavior passed.
Inherited full suite
The historical 46 failure entries were independently classified: 43 reproduce upstream in the named baseline checks; three migration/test failures have subsequent focused passing evidence. Missing CLI dependency and DOM-environment assumptions are identified separately. The full inherited suite is not declared green.
Equivalent rules, local proof
All 393 redirects, 65 conditional routes and the 1,000 bulk redirects match pinned upstream. Twenty local HTTP cases cover redirects, deep links, assets, Markdown negotiation, machine-readable routes and 404s. This is a subset emulator, not a deployed provider acceptance test.
Regional and provider certification
No authoritative new Chinese origin was found; current public Shengwang links still use the legacy origin. Complete regional deployment, provider rule precedence, Accept-negotiated caching and build-image integration remain unverified. The build image must supply Nift explicitly.
The pinned hosting configuration has no explicit cache-header policy, so provider/dashboard defaults cannot be reconstructed from source alone. Four read-only current upstream requests returned correct deep-link HTML, Accept-negotiated Markdown, a Markdown download and a 404; observed responses used public, max-age=0, must-revalidate. This establishes current upstream behavior, not the Nift deployment’s cache correctness. Private Algolia indexing, external-service writes and production API workflows were not exercised. Local Orama fallback was tested. Original CDN assets remain external; this is not a complete offline mirror.
Latest correctness fix is included in reviewed source.
A frontmatter comment can change raw search text without changing the compiled article URL. The authored updater now tracks maintained-source hashes separately. A real YAML-comment test proves correct search updates and exact fixture restoration. This fix follows the captured performance checkpoint and receives no unmeasured speed claim.
08 / maintenance
Our maintenance choice: Nift + TanStack Start.
For this documentation workload, we prefer the Nift-assisted authored-source implementation over the original upstream build workflow.
Our preferred workflow / Nift agora
Keep the application. Maintain one authoritative source.
For maintaining Agora’s documentation, we would choose the Nift-assisted authored-source implementation over the original upstream build workflow. It retains TanStack Start, TanStack Router, React hydration and client navigation while substantially improving observed fresh-build performance and reducing sampled peak build memory.
Dependency-aware publication allows documentation changes to avoid unnecessary application compilation. Markdown/MDX remains authoritative, and search, downloads, metadata and LLM representations are derived together. That is our preference for human maintenance, agent-led maintenance under human direction, and mixed development.
The improvement comes from the surrounding build architecture and reduced repeated work. The original TanStack application remains an important part of the preferred implementation. Removing migration effort and incumbency does not change the authored-source preference.
This recommendation concerns the evaluated documentation workload, not every TanStack application. It justifies a serious Nift-assisted TanStack evaluation for Agora; it is not an unconditional migration decree or a claim of certification in Agora’s live infrastructure. Production hosting, services and regional deployment still need owner review.
09 / methodology
Read the boundaries with the numbers.
Source revisions, workloads and memory scopes are part of the result.
- Fresh application state
- Installed dependencies retained; no generated application/content artifacts. Authored compiles all 1,657 articles. The agent model’s maintained React modules are source, not an unreported generated cache.
- Warm forced publication
- Valid application/content/projections retained. All required pages are rendered and Nift-composed again; this is not a no-op or fresh-source benchmark.
- Process-tree RSS
- Same observer sums simultaneously sampled workload-process-group and descendant RSS, excluding the observer/GNU-time wrapper. Shared pages can be counted more than once and short peaks missed. Requested sleep is 20ms; actual intervals are longer. RSS is not peak physical memory or unique-set size.
- Individual process RSS
- GNU time maximum individual-process RSS is retained separately in canonical samples. It is not interchangeable with the tree-RSS graphs shown here.
- Machine and toolchain
- Recorded environment: Linux 7.0.0-29 x86_64/glibc 2.43, Node 22.22.1, Bun 1.4.3 and Nift 4.12.0. CPU/RAM were not recorded with the benchmark. A later review-time snapshot reports an Intel i7-12700H, 20 logical CPUs and about 61 GiB RAM; it cannot establish historical load or available memory.
- Sampling and provenance
- Two accepted upstream production observations; one Nift observation per model/scenario. No additional upstream or repeated final benchmark campaign. Source representation, cache conditions and production-runtime corrections differ; no statistical dominance or universal latency claim.
10 / evidence
Exact revisions. Retained observations.
Source, raw observations, checks and limitations remain available for inspection.
Canonical evidence is pinned by exact commit and SHA-256 file inventory.
Canonical evidence ↗ · evidence commit 42a602ad49c4
Measured implementations
Reviewed final implementations
The authored revision adds the raw-source correctness fix after measurement. The agent revision adds closeout documentation. Neither later revision is presented as the captured timing source.
Canonical evidence includes commands, exact samples and RSS traces, source/toolchain manifest, output hashes, parity/restoration receipts, classified unit failures, Chinese and hosting qualifications, and independent architecture/correctness/methodology reviews. Evidence lives outside Labs; the website keeps only its compact displayed summary.
Readers can reproduce the project with bun run install:app, bun run build and bun run build:full, with the pinned Node/Bun/Nift toolchain installed. Cloning and dependency installation are outside the measured pipeline.