tanstack-start

Build JSON-defined TanStack Start applications with @json-render/tanstack-start. Use for Start route specs, splat routing, SSR loaders, head metadata, layouts, and client navigation. Do not use for generic TanStack Router apps that do not use json-render.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

@json-render/tanstack-start

Use this integration when a TanStack Start app needs complete pages or routes described by json-render specs.

Install

npm install @json-render/core @json-render/react @json-render/tanstack-start

Application Spec

Include the server-safe built-in definitions in the generation catalog. The renderer supplies their component implementations.

import { defineCatalog } from "@json-render/core";
import {
  schema,
  startComponentDefinitions,
} from "@json-render/tanstack-start/server";

const catalog = defineCatalog(schema, {
  components: {
    ...startComponentDefinitions,
    Card: cardDefinition,
    Shell: shellDefinition,
    Navigation: navigationDefinition,
    Home: homeDefinition,
    Post: postDefinition,
  },
  actions: {},
});

Then use StartAppSpec and TanStack Router route patterns:

import type { StartAppSpec } from "@json-render/tanstack-start";

export const spec: StartAppSpec = {
  metadata: {
    title: { default: "Site", template: "%s | Site" },
  },
  layouts: {
    main: {
      root: "shell",
      elements: {
        shell: { type: "Shell", props: {}, children: ["nav", "slot"] },
        nav: { type: "Navigation", props: {}, children: [] },
        slot: { type: "Slot", props: {}, children: [] },
      },
    },
  },
  routes: {
    "/": {
      layout: "main",
      metadata: { title: "Home" },
      page: {
        root: "home",
        elements: {
          home: { type: "Home", props: {}, children: [] },
        },
      },
    },
    "/posts/$slug": {
      layout: "main",
      loader: "post",
      staticParams: [{ slug: "hello" }],
      page: {
        root: "post",
        elements: {
          post: {
            type: "Post",
            props: { value: { $state: "/post" } },
            children: [],
          },
        },
      },
    },
  },
};

Routes use /posts/$slug for named parameters and /docs/$ for a splat. Splat loader parameters are slash-delimited strings under _splat. Escape route-key slashes as ~1 when generating RFC 6902 patches.

Every layout needs a Slot element. Declare Slot and Link through startComponentDefinitions; do not require consumers to register React implementations for them.

Server Helpers

import { createStartApp } from "@json-render/tanstack-start/server";

export const { getPageData, getHead, getStaticPaths } = createStartApp({
  spec,
  loaders: {
    post: async ({ slug }) => ({ post: await getPost(slug as string) }),
  },
});

State merge precedence is application state, layout state, page state, then loader data. getHead merges app and route metadata into TanStack meta and links descriptors. getStaticPaths includes static routes plus dynamic routes with staticParams. Convert its strings to { path } objects for TanStack Start's top-level pages plugin option. Loader params are URL-decoded, while values from staticParams are URL-encoded in generated paths. Route matching treats trailing slashes as optional and accepts encoded or decoded pathname representations so loader data and metadata resolve the same static route.

Route Wiring

import { createFileRoute, notFound } from "@tanstack/react-router";
import {
  PageRenderer,
  StartErrorBoundary,
  StartLoading,
  StartNotFound,
} from "@json-render/tanstack-start";
import { getHead, getPageData } from "@/lib/json-app";

export const Route = createFileRoute("/$")({
  loader: async ({ location }) => {
    const data = await getPageData({ pathname: location.pathname });
    if (!data) throw notFound();
    return data;
  },
  head: ({ match }) => getHead({ pathname: match.pathname }),
  component: () => <PageRenderer {...Route.useLoaderData()} />,
  pendingComponent: StartLoading,
  errorComponent: StartErrorBoundary,
  notFoundComponent: StartNotFound,
});

TanStack Router loaders run on both the server and client. If a spec factory or named loader uses credentials, database clients, or server-only imports, wrap getPageData and getHead in a TanStack Start createServerFn; do not import that server code directly into an isomorphic route loader.

Root Provider

Wrap the root route's Outlet with StartAppProvider. Render HeadContent so metadata from getHead reaches the document.

import {
  createRootRoute,
  HeadContent,
  Outlet,
  Scripts,
} from "@tanstack/react-router";
import { StartAppProvider } from "@json-render/tanstack-start";
import { spec } from "@/lib/spec";

export const Route = createRootRoute({
  component: () => (
    <html lang="en">
      <head>
        <HeadContent />
      </head>
      <body>
        <StartAppProvider
          registry={registry}
          handlers={handlers}
          spec={spec}
        >
          <Outlet />
        </StartAppProvider>
        <Scripts />
      </body>
    </html>
  ),
});

Use StartLoading, StartErrorBoundary, and StartNotFound for TanStack Router's pendingComponent, errorComponent, and notFoundComponent options. When StartAppProvider receives spec, each component selects the matched route's corresponding fallback. Explicit fallback props override that lookup. Pass named $computed implementations through StartAppProvider.functions. The default error boundary invalidates the router and reruns a failed loader when the user selects Try again.

Import React components from @json-render/tanstack-start. Import schema, createStartApp, matchRoute, resolveMetadata, and static path helpers from @json-render/tanstack-start/server.

Repository: vercel-labs/json-render
Path: skills/tanstack-start/SKILL.md
Commit: c2600d7

Last updated: 1 day ago
First committed: 22 days ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.