TanStack Routerは、ReactとSolidで使うルーティングライブラリです。ルートのパス、パスパラメータ、検索パラメータ、loaderの戻り値までを型として推論するため、存在しないパスへのLinkはコンパイルエラーになり、URLのクエリは検証済みの値として受け取れます。この記事では2026年11月時点の最新版1.170.46を対象に、React Router v8と比べたときの採用条件、導入手順、loaderのキャッシュの動きをコードの実行結果とあわせて説明します。
まとめ
- 型推論とURL検索パラメータの管理を中心に設計されたMITライセンスのルーターです。最新の
@tanstack/react-routerは1.170.46(2026年10月22日公開)で、React 18と19のどちらでも動きます。 - React Router 8.5.1はReact 19.2.7以上とNode.js 22.22以上を要求します。React 18を残すプロジェクトでは、npmの依存解決の段階でv8を入れられません。
- 型の差はフレームワークモードを使わないReact Routerと比べたときに最も開きます。
<Link to="/post">のような綴り違いをコンパイルで止めるのはTanStack Routerです。 - 検索パラメータに依存する
loaderにはloaderDepsが必要です。書かないとURLが変わってもloaderは再実行されず、古いデータが画面に残ります。 - 2026年5月のnpm侵害では1.169.5と1.169.8に悪性コードが混入しました。該当版をインストールした環境は、資格情報の交換まで対応が必要です。
TanStack Routerの現行版と対応環境
1.170系の版番号と動作要件
公式のOverviewは、このライブラリを「ReactとSolidのアプリケーションを作るためのルーター」と位置づけています。npmの値は次のとおりです(2026年11月9日確認)。
| 項目 | 値 |
|---|---|
| @tanstack/react-router | 1.170.46(2026-10-22公開) |
| @tanstack/solid-router | 1.170.43(2.0.0-rc.10もrcタグで公開) |
| @tanstack/router-plugin | 1.169.0(Vite 6以上) |
| React / ReactDOM | 18または19 |
| Node.js(本体) | 20.19以上 |
| Node.js(プラグイン) | ^20.19.0 または 22.12以上 |
| TypeScript | 5.3以上を推奨(必須ではない) |
| ライセンス | MIT |
更新は週単位で進むので、記事の数字よりnpm view @tanstack/react-router versionの結果を正としてください。router-plugin 1.169.0でpeerDependenciesがVite 6以上になったため、Vite 5のプロジェクトは先にViteを上げる必要があります。
Vue版の扱いとReact Locationからの経緯
Quick Startの要件欄にはTanStack Router is currently only compatible with React (with ReactDOM) and Solid
と書かれています。npmには@tanstack/vue-router 1.170.42も公開されていますが、雛形CLIの--frameworkの選択肢もReactとSolidだけです。業務で使うならReactかSolidに限るのが安全です。Solid 2.0向けはRC段階で、peerDependenciesはsolid-js 2.0.0-rc.20以上を要求します。
前身は@tanstack/react-locationで、公式の移行ガイドは型推論とルート定義の方式が異なる別実装として説明しています。v1.0.0のnpm公開は2023年12月23日でした。
React Router v8との違いと選び分け
React Router v8はv7からの移行手順で動作要件を大きく引き上げました。日本語・英語の比較記事の多くはv7のままなので、ここでは8.5.1を相手に、導入条件、型、バンドルサイズの3点を比べます。
React 18を残せるかどうかの導入条件
最初の分岐はReactの版です。React 18のプロジェクトに[email protected]を追加すると、次のエラーで止まります。
$ npm i react@18 react-dom@18 [email protected]
npm error code ERESOLVE
npm error Could not resolve dependency:
npm error peer react@">=19.2.7" from [email protected]
同じ条件で@tanstack/[email protected]は問題なく入ります。React 19へすぐ上げられない業務アプリで、ルーターだけ先に新しくしたい場合の候補はTanStack Routerです。React Routerを使い続けるならversion-7タグの7.18.5が受け皿です。Node.jsもv8は22.22以上、TanStack Routerの本体は20.19以上と開きがあります。
同じ書き間違いに対する型検査の差
TypeScript 7.0.2で同じ書き間違いをコンパイルした結果です。React Router側はフレームワークモードの型生成を使わない構成(Data ModeとDeclarative Modeで共通のAPI)です。
| 書き間違い | TanStack Router | React Router 8.5.1 |
|---|---|---|
| 存在しないパスへのLink | TS2820で停止 | エラーなし |
| 必須のparamsの渡し忘れ | TS2741で停止 | 該当機能なし |
| paramsのキーの綴り違い | TS2353・TS2339で停止 | string | undefinedで通過 |
| 検索パラメータの型違い | スキーマの型でTS2322 | 常にstring | null |
TanStack Routerの1行目のエラーはDid you mean '"/posts"'?まで出します。React Routerもフレームワークモードならルートごとに生成された型でparamsとloaderDataに型が付きますが、<Link to="/nope">の文字列はそのまま通り、href()を通した場合だけTS2345で止まります。検索パラメータもURLSearchParamsのままです。URLのクエリに一覧の条件を持たせる画面が多いほど、この差が実装量に効いてきます。
同条件のgzipサイズ実測
1ルートとLinkだけのアプリをesbuild 0.28.2でバンドルした値です(--bundle --minify --format=esm、NODE_ENVはproduction、gzip -9で圧縮)。ReactとReactDOM 19.3.1の描画処理だけの構成が69,067バイトで、そこからの増分を比べます。
| 構成 | gzip後 | 増分 |
|---|---|---|
| React Router 8.5.1 Declarative | 83,302バイト | +14,235 |
| TanStack Router 1.170.46 | 96,366バイト | +27,299 |
| React Router 8.5.1 Data(createBrowserRouter) | 102,053バイト | +32,986 |
今回の最小構成では、TanStack Routerのgzip後サイズはReact RouterのDeclarative Modeより大きく、createBrowserRouterを使うData Modeより5,687バイト小さくなりました。Vite 8.3.6でビルドしても大小の順序は同じでした。実際の差は、使用する機能やビルド条件によって変わります。
移行工数の見積もり
公式には目安が2つあります。How-toガイドはReact Router v7からの移行を「2〜4時間、難易度Intermediate」とし、インストール節のチェックリストはcould most likely be handled in a sprint cycle or two
と書いています。前者は小規模アプリの手順の所要時間、後者はチームの作業単位と読むのが現実的です。ルート数が多いアプリでは、useSearchParamsで文字列のまま扱っていた箇所をスキーマ付きに書き直す作業も、移行工数に含めて見積もります。React Router側の書き方はReact Router v8の使い方|meta・title設定と基本ルーティング、v7からの変更点とReact Routerのaction・loaderの使い方|clientLoaderとの違い・再検証・バリデーション(v8対応)にまとめています。
TanStack Routerを選ばない場面
次のいずれかに当てはまるなら、TanStack Router単体での採用は見送ります。
- SSRやストリーミングまで一括で欲しい案件。公式のSSR手順はExpressへの手動統合を載せつつ、同じページで
TanStack Start is the recommended way to set up SSR
と案内しています。TanStack Startとは?1.0安定版の変更点と使い方・SEO設定・Bun/Dockerデプロイ【1.169】かNext.jsを選びます。 - React Routerで型の不満がなく、検索パラメータもほとんど使わない既存アプリ。移行の回収先がありません。
- JavaScriptだけのプロジェクト。動きはしますが、中心の価値である型推論を受け取れません。
逆に、APIサーバーが別にあり、検索条件をURLで共有する管理画面をTypeScriptで作るなら、第一候補になります。こうした業務用・Webアプリ開発では、一覧の条件がそのまま型付きのURL状態になる利点が大きいからです。
ViteプロジェクトへTanStack Routerを導入する手順
既存Reactプロジェクトへの追加設定
本体とDevtools、ルートを生成するプラグインを入れます。
npm install @tanstack/react-router @tanstack/react-router-devtools
npm install -D @tanstack/router-plugin
公式のVite手順どおり、プラグインは@vitejs/plugin-reactより前に置きます。autoCodeSplittingを有効にするとルートごとにチャンクが分かれます。
// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { tanstackRouter } from '@tanstack/router-plugin/vite'
export default defineConfig({
plugins: [
tanstackRouter({ target: 'react', autoCodeSplitting: true }),
react(),
],
})
ルートの置き場所を変える場合はプロジェクト直下のtsr.config.jsonでroutesDirectoryとgeneratedRouteTreeを指定します。プラグインはRspack/Rsbuild、Webpack、esbuild用も配布されていますが、esbuild版はautoCodeSplitting: trueでエラーになります。
新規プロジェクトの雛形生成
npx @tanstack/cli create my-app --router-only --blank
Quick Startの--router-onlyだけだと、@tanstack/cli 0.72.16が生成するpackage.jsonにはTailwind CSSとDevtoolsが入ります。--blankを足すと依存からこの2つが外れるため、Tailwind CSSとDevtoolsを含めずに始めたい場合はこちらを選びます。どちらの場合も生成されるVite設定はtarget: 'react'とautoCodeSplitting: trueを含みます。旧来のcreate-tsrouter-appはnpmに残っていますが、公式の案内は@tanstack/cliへ移りました。
ファイルベースルーティングの命名規則とルート定義
ファイル名とURLの対応
公式が大半のプロジェクトに勧めるのはファイルベースです。よく使う記法は次のとおりです。
| 記法 | 意味 | 例 |
|---|---|---|
| __root.tsx | ルートルート(必須) | src/routes/__root.tsx |
| . 区切り | 入れ子のルート | blog.post.tsx |
| $ 接頭 | パスパラメータ | posts.$postId.tsx |
| _ 接頭 | パスなしレイアウト | _app.tsx |
| _ 接尾 | 親の入れ子から除外 | posts_.tsx |
| – 接頭 | ルートツリーから除外 | -components/ |
| (folder) | URLに出ないグループ | (auth)/login.tsx |
| index | 親パスと完全一致 | posts.index.tsx |
ルートファイルは、createFileRouteで作成したルートをRouteという名前でエクスポートします。パス文字列はプラグインが生成・更新するので手で直しません。
// src/routes/posts.$postId.tsx
import { createFileRoute, notFound } from '@tanstack/react-router'
import { fetchPost } from '../api/posts' // 自前のデータ取得関数
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params: { postId } }) => {
const post = await fetchPost(postId)
if (!post) throw notFound()
return { post }
},
notFoundComponent: () => <p>この記事は見つかりませんでした</p>,
component: PostComponent,
})
function PostComponent() {
const { post } = Route.useLoaderData()
return <div>{post.title}</div>
}
createRouterによる生成と型の登録
生成されたrouteTreeをcreateRouterへ渡し、Registerへ宣言のマージで登録します。この宣言を忘れるとLinkのtoは補完されません。
// src/router.tsx
import { createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'
export const router = createRouter({ routeTree })
declare module '@tanstack/react-router' {
interface Register {
router: typeof router
}
}
// src/main.tsx
import ReactDOM from 'react-dom/client'
import { RouterProvider } from '@tanstack/react-router'
import { router } from './router'
ReactDOM.createRoot(document.getElementById('root')!).render(
<RouterProvider router={router} />,
)
createRootRouteとcreateRouteを手で組むコードベース定義も使えます。両者の混在もできるので、既存資産は段階的に移せます。
Outletによるレイアウトのネスト
親ルートの中で子ルートを描画する位置を決めるのがOutletです。propsは取らず、一致する子ルートが無ければ何も描画しません。
// src/routes/__root.tsx
import { createRootRoute, Outlet } from '@tanstack/react-router'
export const Route = createRootRoute({
component: () => (
<div>
<header>共通ヘッダー</header>
<Outlet />
</div>
),
})
公式の説明のとおり、ルートのcomponentを省略するとOutletが自動で描画されます。枠を持たない中間ルートに、Outletを返すだけのコンポーネントを書く必要はありません。
Linkの型安全な遷移
toに渡せるのは登録済みのパスだけで、パラメータ付きのパスではparamsが必須になります。
import { Link } from '@tanstack/react-router'
<Link
to="/posts/$postId"
params={{ postId: 'my-first-post' }}
activeProps={{ className: 'font-bold' }}
>
記事を読む
</Link>
相対指定もでき、to="."で現在のルート、to=".."で1つ上へ移動します。アクティブ判定の条件はactiveOptionsで変えられます。
フォーム送信の成功後のように、副作用の結果として移動するときだけuseNavigateを使います。hrefやCmd/Ctrl+クリックの挙動を持つLinkを基本にするのが公式の推奨です。
const navigate = useNavigate()
await navigate({ to: '/posts/$postId', params: { postId } })
ルートの中ではRoute.useNavigate()を使うと、fromがそのルートに固定され、相対パスの基準がずれません。
パスパラメータと検索パラメータの型安全な取得
useParamsによるパスパラメータの取得
ルートのコンポーネントではRoute.useParams()を使います。$postIdというファイル名からpostIdというキーが型に現れ、別の名前で読むとTS2339になります。ルートに属さない共通部品ではuseParams({ strict: false })を使い、各キーが省略可能になる点に合わせて未定義を確認してください。末尾を丸ごと受けるスプラットルートの値は_splatに入ります。
validateSearchと検索パラメータの実際の値
TanStack Routerの検索パラメータはJSONとして解釈されます。?page=2&tags=%5B1%2C2%5D&num=%222%22は{"page":2,"tags":[1,2],"num":"2"}になり、数値と文字列の区別がURLに残ります。受け取る形はvalidateSearchで決めます。次の例はZod 4.6.7で動かしたものです。
import { createFileRoute } from '@tanstack/react-router'
import { z } from 'zod'
export const Route = createFileRoute('/shop/products')({
validateSearch: z.object({
page: z.number().default(1).catch(1),
filter: z.string().default('').catch(''),
}),
})
.default()と.catch()を重ねているのは、役割が違うからです。.catch(1)だけだと?page=abcは1に落ちますが、そのpageは入力側の型で必須のままなので、<Link to="/shop/products">とsearchを省略した遷移がTS2741になります。.default(1)だけだと省略はできますが、?page=abcで検証エラーになり、errorComponentにSearchParamErrorが届きます。両方を付けると、省略も不正な値も1に落ちます。
公式ガイドにはerror.routerCodeにVALIDATE_SEARCHが入ると書かれていますが、1.170.46ではundefinedでした。@tanstack/react-routerと@tanstack/router-coreの配布コードにもrouterCodeの文字列はありません。判定には@tanstack/react-routerからエクスポートされているSearchParamErrorを使います。
import { ErrorComponent, SearchParamError, type ErrorComponentProps } from '@tanstack/react-router'
function ProductsError({ error }: ErrorComponentProps) {
if (error instanceof SearchParamError) {
return <p>URLの条件が正しくありません</p>
}
return <ErrorComponent error={error} />
}
上のコンポーネントはルートのerrorComponentに指定します。ValibotなどStandard Schemaを実装したライブラリはアダプターなしで渡せます。仕組みはStandard Schemaとは?Zod・Valibot・ArkTypeを共通で受け取る仕組みと実装例で解説しました。ルーターを替えずにURLの状態だけ型安全にしたい場合はnuqsとは?useQueryStateの使い方と2.10までの新機能・debounceの使いどころが選択肢です。
loaderによるデータ取得とキャッシュの既定値
loaderDeps未指定時のページ送りの不具合
検索パラメータで結果が変わるloaderは、loaderDepsで依存する値を宣言します。
export const Route = createFileRoute('/posts/')({
validateSearch: z.object({
offset: z.number().default(0).catch(0),
limit: z.number().default(20).catch(20),
}),
loaderDeps: ({ search: { offset, limit } }) => ({ offset, limit }),
loader: ({ deps: { offset, limit } }) => fetchPosts({ offset, limit }),
component: PostsComponent,
})
書かない場合の公式の説明は「depsが空オブジェクトになる」というものですが、影響はそれだけではありません。jsdom上にReactで実描画し、loaderの実行回数を数えた結果が次の表です。
| loaderDeps | staleTime | 操作 | loader実行 |
|---|---|---|---|
| なし | 既定 | offset 0→20 | 初回のみ |
| なし | 60秒 | offset 0→20 | 初回のみ |
| あり | 60秒 | offset 0→20→0 | 2回(0に戻る時は再利用) |
| あり | 既定 | 別ページへ移動→戻る | 2回 |
| あり | 60秒 | 別ページへ移動→戻る | 1回 |
| あり | 既定 | 先読み→遷移 | 遷移先は先読みの1回のみ |
上の2行が事故の形です。URLのoffsetは20に変わるのに、staleTimeが0でもloaderは動かず、画面には1ページ目のデータが残ります。一覧のページを送っても内容が変わらないときは、まずloaderDepsを確認してください。
キャッシュと先読みの既定値
| オプション | 既定値 | 意味 |
|---|---|---|
| staleTime | 0ミリ秒 | 再訪時に背景で再取得 |
| preloadStaleTime | 30秒 | 先読み結果の鮮度 |
| gcTime / preloadGcTime | 5分 | 未使用データの保持 |
| defaultPreload | false | 先読みは既定で無効 |
| defaultPreloadDelay | 50ミリ秒 | 先読み開始までの待ち |
値はRouterOptionsのAPIリファレンスの記載です。先読みは、ルーターのdefaultPreloadまたは各Linkのpreloadで有効にできます。router.preloadRoute()による明示的な先読みも可能です。'viewport'は画面に入ったリンクすべてが対象になるので、長い一覧ではまず'intent'を選びます。
TanStack Queryを併用するときの責務分担
データの寿命がルートの表示中に閉じるならloaderだけで足ります。画面をまたいで共有する、楽観的更新をする、ミューテーション後に特定のキーだけ無効化する、といった要件が出たらTanStack Queryへ持たせ、loaderは読み込みを待つ役に回します。この場合は鮮度の判断をQueryへ任せるため、公式の案内どおりdefaultPreloadStaleTime: 0を指定します。併用の前提となる既定値はTanStack Queryとは?React Queryとの違い・v5の使い方と既定値の落とし穴を参照してください。
404と取得エラーの分担
データが見つからないときは、前述のコードのようにthrow notFound()でnotFoundComponentへ渡します。既定のnotFoundModeは'fuzzy'で、最も近いルートが処理します。1枚の404画面に集約するなら'root'へ変え、全ルートの受け皿にはcreateRouterのdefaultNotFoundComponentを使います。公式は旧来のNotFoundRouteを非推奨としています。通信失敗などの例外は別系統で、errorComponentが受けます。
SPAとして配信するときのhistoryとbasepath
配信先の制約で選ぶhistoryの種類
| 生成関数 | 使いどころ | URLの形 |
|---|---|---|
| createBrowserHistory | 既定。index.htmlへ書き換え可能 | /posts/1 |
| createHashHistory | 書き換えできない配信環境 | /#/posts/1 |
| createMemoryHistory | ブラウザ以外・テスト | URLに出ない |
公式はhash historyの用途をHash routing can be helpful if your server doesn’t support rewrites to index.html for HTTP requests
と説明しています。リライトを設定できない静的ホスティングでbrowser historyのままにすると、直リンクやリロードが404になります。
サブパス配信とElectronでの設定
ドメイン直下以外へ置くならbasepathを指定します。Electronのようにファイルを直接読み込む構成やテストでは、URLバーに依存しないcreateMemoryHistoryを渡せます。
import { createMemoryHistory, createRouter } from '@tanstack/react-router'
export const router = createRouter({
routeTree,
history: createMemoryHistory({ initialEntries: ['/'] }),
basepath: '/admin',
})
2026年5月のnpm侵害で確認する版
採用や更新の前に確認すべき事故があります。2026年5月11日に42個の@tanstack/*パッケージへ計84個の悪性バージョンが公開されました(GHSA-g7cv-rxg3-hmpx/CVE-2026-45321)。インストール時に実行され、クラウドの認証情報やGitHubトークン、SSH鍵を収集する内容です。
| パッケージ | 悪性バージョン | 修正版 |
|---|---|---|
| @tanstack/react-router | 1.169.5 / 1.169.8 | 1.169.9 |
| @tanstack/router-plugin | 1.167.38 / 1.167.41 | 1.167.42 |
| @tanstack/react-router-devtools | 1.166.16 / 1.166.19 | 1.166.20 |
ロックファイルに該当版があった場合、版を上げるだけでは足りません。その環境でインストールを実行した開発機とCIは侵害済みとして扱い、アドバイザリのAll credentials accessible to the install process should be rotated immediately
に従って資格情報を交換します。2026年9月のCVE-2026-102989は@tanstack/react-startなどStart系だけが対象で、Router単体の構成には影響しません。
よくある質問
TanStackとは何ですか?
TanStackはオープンソースのライブラリ群の名称です。データ取得のTanStack Query、ルーティングのTanStack Router、フルスタックのTanStack Start、フォームのTanStack Formなどがあり、この記事のTanStack Routerはそのうちのルーターにあたります。TanStack StartはRouterの上に作られています。
TanStack Routerは無料で商用利用できますか?
はい。@tanstack/react-routerのライセンスはMITで、npmのメタデータとGitHubリポジトリの両方で確認できます。商用ライセンスの購入は不要です。
React RouterとTanStack Routerはどちらを選ぶべきですか?
検索パラメータを画面の状態として使うSPAをTypeScriptで作るならTanStack Routerです。React 18を残す場合も同じ結論になります。フレームワークモードでSSRまで一括で扱いたい場合と、Declarative Modeで困っていない既存アプリでは、React Routerのままで問題ありません。
Vueでも使えますか?
公式ドキュメントが対応として挙げているのはReactとSolidです。npmに@tanstack/vue-routerはありますが、Vueの業務アプリでは公式の記述が変わるまでVue Routerを使うのが無難です。
TanStack Queryは必須ですか?
必須ではありません。loaderに再検証付きのキャッシュが内蔵されているので、画面をまたいだ共有や楽観的更新が要らないうちは単体で足ります。