start-core

TanStack Start Core

TanStack Start は、TanStack Router と Vite を基盤とするフルスタックの React フレームワークです。SSR、ストリーミング、サーバー関数（型安全な RPC）、ミドルウェア、サーバールート、ユニバーサルデプロイを追加します。

CRITICAL：TanStack Start のすべてのコードは、デフォルトでアイソモーフィックです。つまり、サーバー環境とクライアント環境の両方で実行されます。ローダーはサーバーとクライアントの両方で実行されます。サーバー上でのみコードを実行するには、createServerFn を使用してください。これは AI エージェントが最もよく犯す間違いです。 CRITICAL：TanStack Start は Next.js ではありません。getServerSideProps、"use server" ディレクティブ、app/layout.tsx、Next.js／Remix のパターンを生成しないでください。サーバー専用のコードには createServerFn を使用してください。 CRITICAL：型は完全に推論されます。キャストしたり、推論された値に型注釈を付けたりしないでください。

このエントリースキルを使って、主要なワークフローを1つ選択してください。Start のサブスキルをすべて読み込まないでください。実装がその境界を越える場合にのみ、別のスキルを追加してください。たとえば、保護されたミューテーションには server-functions と auth-server-primitives が必要ですが、公開 REST エンドポイントには server-routes だけが必要です。

サブスキル

タスク	サブスキル
型安全な RPC、データ取得、ミューテーション	start-core/server-functions/SKILL.md
リクエスト／関数のミドルウェア、コンテキスト、認証	start-core/middleware/SKILL.md
サーバーサイド認証：セッション、Cookie、OAuth、CSRF	start-core/auth-server-primitives/SKILL.md
アイソモーフィックな実行、環境の境界	start-core/execution-model/SKILL.md
アプリルートと並行する REST API エンドポイント	start-core/server-routes/SKILL.md
ホスティング、SSR モード、プリレンダリング、SEO	start-core/deployment/SKILL.md

クイック判断ツリー

Need to run code exclusively on the server (DB, secrets)?
  → start-core/server-functions

Need auth checks, logging, or shared logic across server functions?
  → start-core/middleware

Need to add login, sessions, OAuth, CSRF, password reset?
  → start-core/auth-server-primitives

Need to understand where code runs (server vs client)?
  → start-core/execution-model

Need a REST API endpoint (GET/POST/PUT/DELETE)?
  → start-core/server-routes

Need to deploy, configure SSR, or prerender?
  → start-core/deployment

フルスタック開発ワークフロー

Start ルートで読み込むアプリケーションデータの場合：

1. データベース、ファイルシステム、シークレット、永続化のコードは createServerFn の背後に置きます。
2. ルートローダーからサーバー関数を直接呼び出します。SSR ローダーから相対 URL /api/... をセルフフェッチしないでください。
3. すべての入力を検証し、サーバー関数またはミドルウェアで認証を強制します。beforeLoad が保護するのはルートの UX だけです。
4. ミューテーションが解決したら、ルーターまたは外部クエリーキャッシュを無効化し、UI を最新の状態にしてから処理を続ける必要がある場合は、更新の完了を待ちます。
5. スキーマを変更する場合は、ストレージ、検証、ハンドラーのシリアライズ、ローダー、UI を更新します。実際の実行時ペイロードをアサートしてください。型チェックだけでは、シリアライズされたフィールドの欠落を検出できません。

生の HTTP コントラクト自体がプロダクトである場合は、サーバールートを使用します。対象には、Webhook、サードパーティークライアント、フィード、ファイルレスポンス、公開 REST API があります。Start UI とサーバールートでデータを共有する場合は、SSR ローダーから自身の API ルートをフェッチするのではなく、両方から同じサーバーサイドサービスを呼び出します。

完了する前に、初回の SSR リクエスト、クライアントナビゲーション、ミューテーション後の更新、すべての保護対象エンドポイントへの未認証での直接リクエストをテストしてください。

プロジェクトのセットアップ

1. 依存関係をインストールする

npm i @tanstack/react-start @tanstack/react-router react react-dom
npm i -D vite @vitejs/plugin-react typescript

2. Vite を設定する

// vite.config.ts
import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import viteReact from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [
    // MUST come before react()
    tanstackStart(),
    viteReact(),
  ],
})

3. ルーターファクトリーを作成する

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

export function getRouter() {
  const router = createRouter({
    routeTree,
    scrollRestoration: true,
  })

  return router
}

4. ドキュメントシェルを含むルートルートを作成する

// src/routes/__root.tsx
import type { ReactNode } from 'react'
import {
  Outlet,
  createRootRoute,
  HeadContent,
  Scripts,
} from '@tanstack/react-router'

export const Route = createRootRoute({
  head: () => ({
    meta: [
      { charSet: 'utf-8' },
      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
      { title: 'My App' },
    ],
  }),
  component: RootComponent,
})

function RootComponent() {
  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        <Outlet />
        <Scripts />
      </body>
    </html>
  )
}

5. サーバー関数を含むインデックスルートを作成する

// src/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'
import { createServerFn } from '@tanstack/react-start'

const getGreeting = createServerFn({ method: 'GET' }).handler(async () => {
  return { message: 'Hello from the server!' }
})

export const Route = createFileRoute('/')({
  loader: () => getGreeting(),
  component: HomePage,
})

function HomePage() {
  const data = Route.useLoaderData()
  return <h1>{data.message}</h1>
}

よくある間違い

1. 重要：Vite 設定で React プラグインを Start プラグインより前に配置する

// WRONG — route generation and server function compilation fail
plugins: [react(), tanstackStart()]

// CORRECT — Start plugin must come first
plugins: [tanstackStart(), react()]

2. 高リスク：tsconfig で verbatimModuleSyntax を有効にする

verbatimModuleSyntax を有効にすると、サーバーバンドルがクライアントバンドルに漏れます。無効のままにしてください。

3. HIGH：ルートルートに Scripts コンポーネントがありません

<Scripts /> コンポーネントは、ルートルートの <body> 内でレンダリングする必要があります。これがないと、クライアントサイド JavaScript が読み込まれず、ハイドレーションに失敗します。

// WRONG — no Scripts
function RootComponent() {
  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        <Outlet />
      </body>
    </html>
  )
}

// CORRECT — Scripts in body
function RootComponent() {
  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        <Outlet />
        <Scripts />
      </body>
    </html>
  )
}

バージョンに関する注意

このスキルは @tanstack/start-client-core v1.170.14 を対象としています。