ルートの追加は src/routes 以下にファイルを追加することで行います。

npm run dev で開発サーバーが立ち上がっていれば、src/routes 以下にファイルを新規作成すると自動でテンプレートが書き込まれます、便利。

パス区切りの方法

パス区切りにはディレクトリとドットの2つの方法が使えます。

例えばロケーションバーのURLが http://localhost:5173/hoge/fuga のときに表示されるルートは以下の2つの方法で定義できます。

• src/routes/hoge/fuga.tsx
• src/routes/hoge.fuga.tsx

通常はディレクトリ区切りを使い、同じルートで一部表示が変わる場合(src/routes/hoge.modal.tsx)や同じルートの別操作をする場合(src/routes/hoge.edit.tsx)などにドットを使うと良いと思います。

ルートの種類

ルートの種類はたくさんありますが、以下の4つをおさえておけばひとまずコードを書き始められます。その他は必要な場面に遭遇したら改めてドキュメントを読むで良いと思います。

• インデックスルート
• ダイナミックルート
• キャッチオールルート
• パスレスルート

インデックスルート

• ファイル名は ルート名、index.tsx または route.tsx
• routes/posts.tsx、routes/posts/index.tsx、routes/posts/route.tsx が http://localhost/posts にマッチする
• パスと完全一致した場合のみ表示される
• routes/posts.tsx と routes/posts/index.tsx があった場合、/posts.tsxが優先される
  • routes/posts.tsx に <Outlet /> タグがあると、 routes/posts.tsx の中に routes/posts/index.tsx が表示される
• routes/posts.tsx と routes/posts/route.tsx があった場合、エラーになる
  • routes/posts.tsx と routes/posts/route.tsx は同一ルートを意味するので、ルート定義の衝突エラーになる

    Error: Conflicting configuration paths were found for the following routes: “/posts”, “/posts”.

  • route.tsx ファイルは、posts.tsxファイルとpostsディレクトリを別に作らずに、postsディレクトリにファイルをまとめたいときに使う
• ルート名、route.tsxとindex.tsx の違い
  • ルート名、route.tsx は <Outlet /> タグを持つとそこに子ルートの内容を表示する
  • index.tsx は <Outlet /> タグがあっても子ルートの内容を表示しない

ダイナミックルート

• $で始まるパスはパラメータになり、paramsオブジェクトで参照できる
• posts/$postIdが http://localhost/posts/123 にマッチし、 params.postId に 123 が入る

キャッチオールルート

• $のみ のルートはキャッチオールルートになり、パス区切りに関係なくそれ以降の全てにマッチする
• posts/$ が　http://localhost/posts/xxx と http://localhost/post/xxx/yyy のどちらにもマッチする
• マッチした部分は params._splat プロパティで参照できる

パスレスルート

• _ で始まるルートはどのパスにもマッチしない
• 子ルートをラップして、ミドルウェアのようにいろいろな機能を提供するのに使われる
  • 共通レイアウトの適用
  • 共通 loader の実行
  • 共通パラメーターの検証
  • 共通エラーコンポーネントの定義
  • 共通コンテキストの追加
• _layout.tsx がある場合、_layout.index.tsx あるいは _layout/index.tsx が http://localhost/ にマッチし、_layout.tsx の <Outlet /> に _layout.index.tsx あるいは _layout/index.tsx の内容が表示される

ネスト解除ルート

• _ で終わるルートはルートコンポーネントの入れ子構造の一段階上になる
• 特定のパスだけレイアウトを外したい場合など
• https://tanstack.com/router/latest/docs/framework/react/routing/routing-concepts#non-nested-routes

無視されるルート

• - で始まるファイルは無視される、ファイルの自動生成も動かない。

Not Foundルート

• 廃止予定 https://tanstack.com/router/latest/docs/framework/react/guide/not-found-errors/#migrating-from-notfoundroute
• 代わりに各 routeの notFoundComponent を使う

APIルート

• /routes/api はAPIルートのための特別なディレクトリとして予約されている
• APIルートには外部に公開するAPIを置く
• APIルートの場所を /routes/api 以外にしたい場合、tsr.config.json の apiBase を変更する

バーチャルファイルルート

• パスとルートの割当をコードで変更できる機能
• https://tanstack.com/router/latest/docs/framework/react/routing/virtual-file-routes
• ファイルベースルーティングの一部だけをバーチャルファイルルートにすることもできる
  • https://tanstack.com/router/latest/docs/framework/react/routing/virtual-file-routes#virtual-routes-inside-of-tanstack-router-file-based-routing

ディレクトリを（）で囲むとパスとしては認識されなくなる

• ディレクトリをファイルをまとめるためだけに使えるようになる
• https://tanstack.com/router/latest/docs/framework/react/guide/routing-concepts#pathless-route-group-directories

まとめ

• パスの区切りはディレクトリ化ドットで行う
• よく使うルートはインデックス・ダイナミック・キャッチオール・パスレスの4種類