Integration study / 001 · Independent experiment; no TanStack endorsement.
Greenfield systems / October 2026
Nift generates the website.
TanStack powers the interactions. Three architectures and 3,000 documents explore how these responsibilities fit together.
The engineering recommendation
For this documentation-heavy website with selective interactivity, we’d choose Nift-first with TanStack islands. Full publication is faster, peak build memory is lower, and ordinary articles deliver much less JavaScript.
Adding Nift dependency management to our already optimised Start implementation did not improve this particular workflow. That does not establish the best full-stack architecture. We did not evaluate a standalone Nift full-stack application, and these configurations do not provide identical server-side capabilities.
The control still wins unchanged and individual document-edit builds. These are single observations, and the architectures do not provide identical server-side contracts.
01 / architectures
The final comparison contains three 3,000-document configurations. An earlier 62-guide prototype explains how we reached them.
The first prototype gave Nift an independent docs shell beside a Start application. It worked, with cheap documentation updates, but separate HTML/JSX layouts and document-to-app navigation added maintenance seams. For that prototype, the assessment preferred the TanStack-only implementation. This smaller, different workload is preserved; its timings are not mixed into the charts below.
Preserved first experimentIntegrated Nift + Start
Phase 2 fixed the split-shell boundary. Nift selects dependencies and publishes JSON before Start SSR; it does not replace the expensive React rendering.
Finding Functional integration; no compelling advantage over the optimised control.
Optimised TanStack Start
Stable bundles, isolated compilation, bounded workers and stage caches benefit this implementation too. It is not an intentionally expensive control.
Finding Best measured unchanged/docs-edit loop; the better measured trade-off of the two Start-based implementations.
Nift-first + TanStack islands
Query, Table, Virtual and Form power a real explorer. The existing dashboard runs in an embedded Router workspace. Ordinary articles do not hydrate a React document.
Finding Our choice for this static-heavy portal; a different application contract.
This is a greenfield PulseOps fixture, not a migration of TanStack.com. That separate migration/rewrite investigation retains its own conclusions. Agora Docs remains a production-site migration.
02 / contract
Equivalent document content and working interactions do not imply an identical application framework contract.
| Responsibility | A · Integrated | B · Optimised Start | C · Nift-first |
|---|---|---|---|
| Shared page layout | React / Start | React / Start | Nift HTML templates |
| Docs ↔ app navigation | Unified client Router | Unified client Router | Full document navigation |
| Documentation interactivity | Whole document hydration | Whole document hydration | Local React mounts |
| Workspace initial rendering | Start SSR | Start SSR | Client-rendered; JavaScript required |
| Server-function lifecycle | Retained Start | Retained Start | Static fixture APIs; not equivalent |
| App compilation after docs edit | Skipped | Skipped | Skipped |
| Search after content edit | Full index regeneration | Full index regeneration | Full index regeneration |
All 3,000 articles retain their heading text/anchors, table-cell content and highlighted code. Search bytes match the unchanged control; every published local link, image and script target resolves. Browser checks exercise authored/generated MDX tabs and calculators, search, dashboard data, deployment filters/details, capacity controls and saved settings.
A fresh agent fixed Form validation/accessibility from the source map; parent browser checks separately confirmed empty-submit rejection, a stable input label and valid local submission. The API explorer uses real Query loading, Table sorting/filtering and Virtual scrolling—not merely installed packages.
Nift-first emits 3,089 HTML entry pages, including workspace entry wrappers and the additional explorer. Start configurations emit 3,002 static pages plus runtime application routes. The wrappers are not prerendered dashboards.
The corpus preserves 62 original guides and expands through deterministic fictional, versioned reference generation. It is not 3,000 independently authored production articles. A clean GitHub checkout reproduced all 3,102 publication files byte-for-byte. These are representative functional checks, not certification of every viewport or a production deployment.
03 / measurements
Zero-origin linear bars. Each panel states its own axis maximum; compare configurations within a panel.
One observation per case. Not medians. The earlier Phase 2 cohort is retained unchanged, not interleaved with the islands run. Warm publication reuses valid compilation in every configuration; fresh means fresh application state, not a cold OS cache.
Nift-first avoids Start/React rendering for ordinary Markdown and whole-document hydration in the browser. Its fresh observation is about 30% faster than the optimised control, with about 31% lower sampled tree RSS. Warm full publication is about three times faster.
Markdown uses a standard Markdown/GFM/highlighting pipeline; MDX still uses the official compiler and build-time React static rendering. The final fresh compilation/rendering stage costs 11.99s. The 979 MDX sources are not free, and these are not native @markup performance results.
04 / iteration
Time and peak memory stay attached to the same incremental workload.
The control wins the small-update cases. Nift-first still walks/hashes content and body data, prepares recipes and traverses the native graph. A document edit also regenerates the global search index. These fixed costs remain future profiling targets.
Shared layout means a React root-layout change in A/B and the common Nift header in C—equivalent site-wide purpose, different implementation boundaries. Both publish all affected pages. Other diagnostic cases and component costs remain in the pinned source report.
| Scenario | A · Integrated | B · Optimised Start | C · Nift-first |
|---|---|---|---|
| fresh | 25.20s / 341.5 MiB | 23.12s / 356.5 MiB | 16.12s / 188.7 MiB |
| warm full | 8.59s / 163.6 MiB | 7.30s / 176.2 MiB | 2.45s / 142.8 MiB |
| unchanged | 0.859s / 58.8 MiB | 0.168s / 61.9 MiB | 1.150s / 69.9 MiB |
| docs edit | 1.76s / 164.4 MiB | 1.12s / 158.2 MiB | 2.07s / 143.3 MiB |
| shared layout | 8.92s / 335.8 MiB | 8.16s / 330.3 MiB | 1.77s / 70.6 MiB |
Linux descendant-process RSS is sampled at a 2ms target interval; actual gaps are recorded. The tree peak sums simultaneously resident descendants, can double-count shared pages, and can miss short peaks. It excludes the observer and is neither PSS nor total machine memory. GNU time’s maximum individual-process/phase RSS is retained separately above. No sum of individual maxima is presented as aggregate memory.
05 / javascript
The delivery result is selective loading, not a smaller whole-site asset directory.
The static guide loads a tiny vanilla shell for theme and tab-note behavior. Interactive MDX loads React and a component entry. Search loads its own script on the documentation index; the workspace and explorer have separate entries.
| Page | A · Integrated | B · Optimised Start | C · Nift-first |
|---|---|---|---|
| Ordinary guide | 395,711 B | 395,711 B | 746 B |
| Interactive MDX guide | 395,711 B | 395,711 B | 221,084 B |
| All published JavaScript | 419,381 B | 419,381 B | 466,002 B |
Including executable inline scripts in HTML, the Start totals are 404,056 B for the ordinary guide and 405,272 B for MDX. Nift-first has no executable inline script on those sampled articles. These are uncompressed response bodies—not compressed network transfer, HTTP/TLS overhead, latency or Web Vitals. The additional Query/Table/Virtual/Form explorer makes Nift-first’s total published JS larger; ordinary readers load less of it.
06 / lessons
The recommendation changed after a different ownership model was tested—not after weakening the control.
It is a strong fit when articles dominate and interactive regions are bounded. Faster full publication, lower peak memory and lighter ordinary-page delivery are material here. It does not win unchanged or individual docs edits.
Nift-first combines islands with a bounded workspace in this implementation. The Start configurations retain continuous Router state, shared query context and SSR across the application. Docs↔app document navigation is a tradeoff here, not an inherent limitation of Nift or a verdict on other architectures.
Of the two Start-based configurations tested, the optimised control offered the better measured trade-off. This Nift-first implementation deliberately does not reproduce Start’s server-function lifecycle; fixture-backed JSON is not equivalent. We did not compare a standalone Nift full-stack architecture or establish that Start is generally preferable for full-stack development.
Isolated MDX compilation, bounded workers, stable bundles and caching helped both Start implementations. They are not exclusive Nift gains. This experiment does not prove that only Nift could implement an efficient static-first site.
Nift-first lets ordinary authors use Markdown, HTML and CSS. A new interactive MDX component still needs an island entry and an explicit fallback/provider boundary. Its simple development watcher requires a manual reload; it does not match the reference’s React HMR experience.
The first islands pass retained the search heap and traversed the graph twice. Correcting those costs helped. A later regression exposed literal-template and failed-intermediate recovery bugs; fixing them added validation cost. The final fresh build is 16.12s, not the faster pre-fix observation.
Future work includes cheaper unchanged planning, incremental search, simpler island registration and better development-server integration. Those are future Nift/tooling targets, not reasons to rewrite this result. No Nift core changes were made.
07 / evidence
Canonical evidence stays in the experiment repository. Labs keeps only this compact displayed summary.
The separate clean clone reproduced all 3,102 publication files byte-for-byte. Both earlier reference implementations and their reports remain unchanged. Hash-verified source pointers are recorded in the Labs evidence index; normal site builds need no network or experiment checkout.
Independent greenfield research. Generated fixture corpus. Single observations. Different application contracts. Representative browser checks. No production deployment certification or TanStack endorsement.