/start-core

name: start-core
version: 1.0.0
description: Use when scaffolding a TanStack Start project, wiring the build tool, or debugging setup (blank page, hydration, no client JS).
user-invocable: true
references: references/project-setup.md, references/project-anatomy.md, references/common-mistakes.md, references/templates/minimal-project.md

<objective> Covers TanStack Start project setup and anatomy: the tanstackStart() Vite (and Rsbuild) plugin, the getRouter() factory, the root route document shell (HeadContent, Outlet, Scripts), the generated routeTree.gen.ts, tsconfig, and overall src/ layout. Targets @tanstack/react-start v1.169.5.

States the framework's identity clearly: Start is built on TanStack Router + Vite, not Next.js — no getServerSideProps, no "use server" directives, no app/layout.tsx. Routes live in src/routes/, server-only code uses createServerFn, code is isomorphic by default (loaders run on both server and client), and types are fully inferred (never cast or annotate inferred values).

Documents the two hand-written wiring files every app needs (src/router.tsx, src/routes/__root.tsx) plus the one generated file that must never be edited (routeTree.gen.ts), a minimal Vite config, and the CLI scaffolding shortcut.

Do NOT use this skill for server-only vs isomorphic execution boundaries in depth (use start-execution-model), for SOLID/code organization (use solid-tanstack-start), or for a plain React SPA without Start. </objective>

TanStack Start Core

TanStack Start is a full-stack React framework built on **TanStack Router + Vite** (Rsbuild also supported). It adds SSR, streaming, server functions (type-safe RPCs), middleware, and universal deployment. This skill targets `@tanstack/react-start` **v1.169.5**.

> **CRITICAL — Start is NOT Next.js.** No `getServerSideProps`, no `"use server"` > directives, no `app/layout.tsx`. Routes live in `src/routes/`; server-only code > uses `createServerFn`. > > **CRITICAL — code is isomorphic by default.** Loaders run on server AND client. > See the `start-execution-model` skill before putting logic in a loader. > > **CRITICAL — types are fully inferred.** Never cast or annotate inferred values.

Agent Workflow (MANDATORY)

Before implementing, verify current APIs against Context7 (`/websites/tanstack_start_framework_react`) + Exa, then explore the target codebase. After changes, run `fuse-ai-pilot:sniper`.

---

The Two Required Files

Every Start app needs exactly two hand-written wiring files plus one generated:

1. **`src/router.tsx`** — a `getRouter()` factory returning `createRouter({ routeTree })`. 2. **`src/routes/__root.tsx`** — the document shell (`<html>`, `HeadContent`, `Outlet`, `Scripts`). 3. **`src/routeTree.gen.ts`** — GENERATED by the plugin. Never edit.

---

Minimal Setup (glance)

// vite.config.ts — Start plugin MUST come before React's
import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import viteReact from '@vitejs/plugin-react'

export default defineConfig({
  server: { port: 3000 },
  plugins: [tanstackStart(), viteReact()],
})

// src/router.tsx
import { createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

export function getRouter() {
  return createRouter({ routeTree, scrollRestoration: true })
}

Full walkthrough → `references/project-setup.md`. Full file tree and each file's role → `references/project-anatomy.md`. Complete copy-paste project → `references/templates/minimal-project.md`.

---

Reference Guide

| Topic | Reference | Load when | |-------|-----------|-----------| | Install, Vite + Rsbuild config, package.json, tsconfig | `references/project-setup.md` | scaffolding, wiring the build tool | | `src/` layout, `getRouter`, `__root.tsx`, generated tree | `references/project-anatomy.md` | understanding where files go | | Plugin order, missing `<Scripts />`, `verbatimModuleSyntax` | `references/common-mistakes.md` | blank page, hydration fails, no client JS | | Full minimal project (every file) | `references/templates/minimal-project.md` | starting a new app |

---

Scaffolding Shortcut

Instead of building by hand, the CLI scaffolds a working project:

npx @tanstack/cli@latest create
# or clone an official example:
npx gitpick TanStack/router/tree/main/examples/react/start-basic start-basic

---

Forbidden

• React Vite plugin placed before `tanstackStart()` (breaks generation).
• Editing `src/routeTree.gen.ts` (generated).
• Omitting `<Scripts />` in `__root.tsx` (no hydration).
• Enabling `verbatimModuleSyntax` (leaks server code into client bundle).
• Next.js/Remix patterns (`getServerSideProps`, `"use server"`).