react-start

React Start (@tanstack/react-start)

これは React Start のエントリースキルです。以下のワークフローに従ってから、変更する境界を担当するパッケージのスキルだけを読み込んでください。作業を始める前に、start-core、Router Core、React Router のマニュアルをすべて読まないでください。

React Server Components のパターンについては、react-start/server-components を参照してください。

CRITICAL：すべてのコードはデフォルトでアイソモーフィックです。ローダーはサーバーとクライアントの両方で実行されます。サーバー専用ロジックには createServerFn を使用してください。

CRITICAL：@tanstack/react-start を Next.js や Remix と混同しないでください。これらは API が異なる、まったく別のフレームワークです。

CRITICAL：型は完全に推論されます。キャストや、推論される値への型注釈は行わないでください。

フルスタックのワークフロー

1. createFileRoute を使ってルートとコンポーネントを定義します。
2. プライベートまたはサーバー専用の読み書き処理は createServerFn に記述し、読み取り処理はローダーから直接呼び出します。
3. コンポーネントからの変更処理には useServerFn を使用し、書き込み処理の完了後にルーターまたはクエリーキャッシュを無効化します。
4. すべてのプライベートなサーバー関数またはサーバールートで認証を強制します。ナビゲーションの UX には、別途 beforeLoad を追加します。
5. 初回の SSR パス、クライアントナビゲーション、変更処理と再読み込み、匿名での直接エンドポイントリクエスト、実行時のレスポンスアサーション、型テスト、本番ビルドを実行します。

生の HTTP エンドポイントが必要な場合に限り、server-functions ではなく start-core/server-routes を読み込みます。router-core/* は、パラメーターや検索値のバリデーションなど、関係する特定のルーティング上の懸念に限って読み込みます。

パッケージ API の公開範囲

@tanstack/react-start は、@tanstack/start-client-core のすべてのエクスポートに加えて、以下を再エクスポートします。

• useServerFn — コンポーネントからサーバー関数を呼び出すための React フック

すべてのコア API（createServerFn、createMiddleware、createStart、createIsomorphicFn、createServerOnlyFn、createClientOnlyFn）は、@tanstack/react-start から利用できます。

サーバーユーティリティ（getRequest、getRequestHeader、setResponseHeader、setResponseHeaders、setResponseStatus）は、@tanstack/react-start/server からインポートします。

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

1. 依存関係のインストール

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

2. package.json

{
  "type": "module",
  "scripts": {
    "dev": "vite dev",
    "build": "vite build",
    "start": "node .output/server/index.mjs"
  }
}

3. tsconfig.json

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "moduleResolution": "Bundler",
    "module": "ESNext",
    "target": "ES2022",
    "skipLibCheck": true,
    "strictNullChecks": true
  }
}

4. 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: [
    tanstackStart(), // MUST come before react()
    viteReact(),
  ],
})

5. ルーターファクトリー（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
}

6. ルートルート（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 TanStack Start App' },
    ],
  }),
  component: RootComponent,
})

function RootComponent() {
  return (
    <RootDocument>
      <Outlet />
    </RootDocument>
  )
}

function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  )
}

7. インデックスルート（src/routes/index.tsx）

import { createFileRoute } from '@tanstack/react-router'
import { createServerFn } from '@tanstack/react-start'

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

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

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

useServerFn フック

適切に連携させて React コンポーネントからサーバー関数を呼び出すには、useServerFn を使用します。

import { createServerFn, useServerFn } from '@tanstack/react-start'

const updatePost = createServerFn({ method: 'POST' })
  .validator((data: { id: string; title: string }) => data)
  .handler(async ({ data }) => {
    await db.posts.update(data.id, { title: data.title })
    return { success: true }
  })

function EditPostForm({ postId }: { postId: string }) {
  const updatePostFn = useServerFn(updatePost)
  const [title, setTitle] = useState('')

  return (
    <form
      onSubmit={async (e) => {
        e.preventDefault()
        await updatePostFn({ data: { id: postId, title } })
      }}
    >
      <input value={title} onChange={(e) => setTitle(e.target.value)} />
      <button type="submit">Save</button>
    </form>
  )
}

グローバル Start 設定（src/start.ts）

import { createStart, createMiddleware } from '@tanstack/react-start'

const requestLogger = createMiddleware().server(async ({ next, request }) => {
  console.log(`${request.method} ${request.url}`)
  return next()
})

export const startInstance = createStart(() => ({
  requestMiddleware: [requestLogger],
}))

React 固有のコンポーネント

@tanstack/react-router のすべてのルーティングコンポーネントは Start で動作します。

• <RouterProvider> — Start では不要です（自動的に処理されます）
• <Outlet> — マッチした子ルートをレンダリングします
• <Link> — 型安全なナビゲーション
• <Navigate> — 宣言的なリダイレクト
• <HeadContent> — head タグをレンダリングします（<head> 内に置く必要があります）
• <Scripts> — body スクリプトをレンダリングします（<body> 内に置く必要があります）
• <Await> — Suspense を使って遅延データをレンダリングします
• <ClientOnly> — ハイドレーション後にのみ子要素をレンダリングします
• <CatchBoundary> — エラーバウンダリー

フックのリファレンス

@tanstack/react-router のすべてのフックは Start で動作します。

• useRouter() — ルーターインスタンス
• useRouterState() — ルーターの状態を購読します
• useNavigate() — プログラムによるナビゲーション
• useSearch({ from }) — バリデーション済みの検索パラメーター
• useParams({ from }) — パスパラメーター
• useLoaderData({ from }) — ローダーデータ
• useMatch({ from }) — ルートの完全なマッチ情報
• useRouteContext({ from }) — ルートコンテキスト
• Route.useLoaderData() — 型付けされたローダーデータ（ルートファイルではこちらを推奨）
• Route.useSearch() — 型付けされた検索パラメーター（ルートファイルではこちらを推奨）

よくある間違い

1. CRITICAL：誤ったパッケージからインポートする

// WRONG — this is the SPA router, NOT Start
import { createServerFn } from '@tanstack/react-router'

// CORRECT — server functions come from react-start
import { createServerFn } from '@tanstack/react-start'

// CORRECT — routing APIs come from react-router (re-exported by Start too)
import { createFileRoute, Link } from '@tanstack/react-router'

2. HIGH：beforeLoad またはローダー内で React フックを使用する

// WRONG — beforeLoad/loader are NOT React components
beforeLoad: () => {
  const auth = useAuth() // React hook, cannot be used here
}

// CORRECT — pass state via router context
const rootRoute = createRootRouteWithContext<{ auth: AuthState }>()({})

3. HIGH：Scripts コンポーネントがない

ルートルートの <body> 内に <Scripts /> がないと、クライアント JavaScript が読み込まれず、アプリはハイドレーションされません。

相互参照

• @tanstack/start-client-core#start-core — Start のコア概念
• @tanstack/router-core#router-core — ルーティングの基礎
• @tanstack/react-router#react-router — React Router のフックとコンポーネント