[Deep Dive #45] Route Shell Tutorial Vault - discussion

Treating tutorials as vault artifacts is smart. People copy them anyway; making them explicit reduces the 'cargo cult' effect.

Related: Examples and Tutorials.

We render a tiny mode marker in our app shell: csr|ssr|rsc per route. It sounds trivial but it solved so many bug reports.

If you're mixing modes, you need mode evidence.

Single-component admin UI is absolutely a posture. The benefit is coherence: one file, one surface, fewer hidden cross-component contracts.

The downside is you end up with a single component that is secretly a whole app.

Dashboard tutorial being treated as 'best practices' is nice because dashboards are where people invent their own caching rules.

If the tutorial vault gives you a default lane, teams stop arguing in circles.

My only ask: if tutorials are vault artifacts, they should also link to the glossary terms they introduce (shell, posture, lane).

Otherwise everyone copies the code but uses different words for the same thing.

The blog (CSR/SSR/RSC) tutorial callout is a good reminder that 'blog app' is not trivial anymore.

If the tutorial doesn't render mode evidence, the forum should encourage adding it.

We actually treat tutorials as canonical until proven otherwise, mostly because it keeps debates short.

If someone wants to deviate, they have to show the evidence and update our internal shell doc.

On the mode marker, the simplest thing we shipped was just a route-visible string based on how the shell was composed:

tsx
import { useRouteState } from "react";

export function RenderModeBadge() {
  const route = useRouteState();
  const mode = route.read("renderMode"); // 'csr' | 'ssr' | 'rsc'
  return <span data-render-mode={mode}>{mode}</span>;
}

Then tests snapshot it. That was the big win: every regression is visible in diffs.

Counterpoint on single-component admin: it only works if you treat it as a *route surface* with its own internal component router.

If it's literally one giant component with no internal contracts, it becomes impossible to migrate.

The vault framing also changes maintenance: you can update the tutorial shell and then rebase multiple examples without rewriting every page.

If you keep the shell contract stable, examples become "fixtures" instead of one-off demos.