TanStack Routerのファイル命名規則について14個の覚え書き

はじめに

この記事はTanStack Routerのファイルの命名規則についてまとめたものになります。
TanStack Routerを使い始めた方の理解の助けになれば幸いです。

ファイル命名一覧

1. __root.tsx - ルートファイル

すべてのルートの親となる必須ファイルです。routesフォルダ内に配置される必要があります。
このファイル内にアプリ全体のレイアウト設定や、各種ライブラリのプロバイダーを配置します。また、createRootRouteWithContext関数を利用することでルートコンテキストの作成ができます。
以下の例はTanstack Queryのクライアントをコンテキストに設定する例です。

src/routes/__root.tsx : 一般例

import { createRootRoute, Outlet } from "@tanstack/react-router";

export const Route = ({
  component: () => (
    <>
      <Outlet />
    </>
  ),
});

src/routes/__root.tsx : コンテキストを設定する例

import { createRootRouteWithContext, Outlet } from "@tanstack/react-router";
import type { QueryClient } from "@tanstack/react-query";

export const Route = createRootRouteWithContext<{
  queryClient: QueryClient;
}>()({
  component: () => (
    <>
      <Outlet />
    </>
  ),
});

2. index.tsx

インデックスルートは親ルートと完全に一致する場合にマッチする特殊なルートです。
indexトークンがファイル名に含まれることで、そのルートの親パスと完全に同じURLでアクセスされた際に表示されます。
例えば、ルート直下のindex.tsxは/パスでアクセスしたときのホームページとなり、postsフォルダ内のindex.tsxは/postsでアクセスしたときに表示されるルートとなります。

Next.jsを利用している方は、page.tsxをindex.tsxと読み替えてみると理解がしやすいかもしれません

src/routes/index.tsx

export const Route = createFileRoute('/')({
  component: () => <div>ホームページ</div>,
})

3. ベースルート

ベースルートは、ファイル名でルートを作成するパターンになります。
例えばabout.tsxは/aboutパスに、contact.tsxは/contactパスに対応します。

先程のindex.tsxはフォルダでパスを区切っていくのに対して、このベースルートはファイルでパスを区切っていきます。

// src/routes/about.tsx
export const Route = createFileRoute('/about')({
  component: () => <div>About Page</div>,
})

4. . セパレータ - ネストしたルート

ドット記号（.）を使用することで、ルートの階層構造を表現できます。parent.child.tsxの形式で命名することにより、/parent/childのようなネストしたパスが生成されます。
この方法の最大のメリットは、深い階層のルートでもディレクトリを作成する必要がないことです。
例えばblog.post.edit.tsxというファイル一つで/blog/post/editパスが作成できます。

// src/routes/blog.post.tsx
export const Route = createFileRoute('/blog/post')({
  component: () => <div>Blog Post</div>,
})

5. $ トークン - 動的パラメータ

$記号を使用することで、URL内の動的なパラメーターを取得できます。
$paramName.tsxの形式で命名することにより、その部分が変数として扱われ、コンポーネント内でuseParamsフックを通じて値を取得できます。

例えばposts.$postId.tsxは/posts/123や/posts/abcなどの様々な値にマッチし、postIdとして値を取得できます。

// src/routes/posts.$postId.tsx
export const Route = createFileRoute('/posts/$postId')({
  component: () => {
    const { postId } = Route.useParams()
    return <div>Post ID: {postId}</div>
  },
})

6. {$} - スプラットルート（ワイルドカード）

スプラットルートは残りのパス全体をキャプチャする特殊な動的ルートです。
{$}または$.tsxの形式で定義され、マッチした値は_splatという特殊なパラメータ名で取得できます。
これはファイルパスのような深い階層構造や、予測できない長さのパスを処理する際に便利です。

例えばfiles.$.tsxは/files/documents/folder/file.txtのような任意の深さのパスにマッチします。

// src/routes/files.$.tsx
export const Route = createFileRoute('/files/$')({
  component: () => {
    const { _splat } = Route.useParams()
    return <div>File Path: {_splat}</div>
  },
})

7. {-$paramName} - オプショナルパラメータ

{-$paramName}.tsxの形式で定義することで、そのセグメントが存在しない場合でもルートにマッチするようになります。
例えばposts.{-$category}.tsxは/postsと/posts/techの両方にマッチし、カテゴリが指定されていない場合はパラメータの値がundefinedとなります。

// src/routes/posts.{-$category}.tsx
export const Route = createFileRoute('/posts/{-$category}')({
  component: () => {
    const { category } = Route.useParams()
    return <div>{category ? `Category: ${category}` : 'All Posts'}</div>
  },
})

8. プレフィックス・サフィックス付きパラメータ

動的パラメータの前後に固定文字を付けることで、より具体的なパターンマッチングが可能になります。
例えばuser-{$userId}person.tsxは/user-123personのような特定の形式にのみマッチします。これはAPIのバージョニングや特定のファイル拡張子を持つリソースへのルーティングなどで活用できます。

// src/routes/api.v{$version}.tsx
export const Route = createFileRoute('/api/v{$version}')({
  component: () => {
    const { version } = Route.useParams()
    return <div>API Version: {version}</div>
  },
})

9. _ プレフィックス - パスレスレイアウトルート

アンダースコア（_）をプレフィックに使用することで、URLパスに含まれないレイアウトルートを作成できます。
これらのルートは子ルートをラップする役割を持ちますが、URLには直接影響しません。認証が必要なページをグループ化したり、共通のレイアウトを適用したりする際に便利です。
例えば_auth.tsxレイアウト内に_auth.login.tsxを配置すると、/loginパスでアクセス可能になります。

// src/routes/_auth.tsx
export const Route = createFileRoute('/_auth')({
  component: () => (
    <div className="auth-layout">
      <Outlet />
    </div>
  ),
})

// src/routes/_auth.login.tsx → /login
// src/routes/_auth.register.tsx → /register

10. _ サフィックス - 親ルートから除外

ファイル名の末尾にアンダースコア（_）を付けることで、そのルートを親ルートの下にネストさせないように指定できます。これにより独立したルートとして扱われ、親ルートのレイアウトやコンテキストの影響を受けません。特定のページだけ異なるレイアウトを適用したい場合などに利用できます。

// src/routes/posts_.edit.tsx
// 親の posts.tsx の影響を受けない独立したルート

11. - プレフィックス - ルートツリーから除外

フォルダの先頭にハイフン（-）をつけることで、ルートツリーから除外することができます。ルートフォルダ内にcomponentやutlilsなどを配置する際に便利です。
Next.jsでいうところのapp/_components/と同じ働きをします。

// src/routes/-utils.ts
// src/routes/-components/Header.tsx
// これらはルートとして認識されない

12. (folder) - ルートグループ

括弧で囲まれたフォルダ名は、URLパスに含まれないルートグループとして扱われます。これはルートをカテゴリ別で整理する際に使用され、フォルダ名自体はURLに反映されません。
例えば(dashboard)フォルダ内にanalytics.tsxを配置すると、/analyticsパスでアクセス可能になり、ダッシュボードという括りでルートをグループ化できます。

src/routes/
├── (dashboard)/
│   ├── analytics.tsx → /analytics
│   └── reports.tsx → /reports

13. [x] - エスケープ文字

角括弧（[ ]）を使用することで、通常はルーティングで特別な意味を持つ文字をエスケープできます。
例えばscript[.]js.tsxは/script.jsパスを生成し、api[.]v1.tsxは/api.v1パスを生成します。これにより実際のファイル拡張子を含むURLや、ドット記号を文字通りの意味で使用したいパスを作成できます。

// src/routes/api[.]json.tsx → /api.json

14. .route.tsx - ディレクトリルートファイル

ディレクトリ構造を使用してルートを整理する際に、特定のディレクトリパスに対応するルートファイルを指定するために使用されます。route.tsxという名前、またはparent.route.tsxの形式で命名することで、そのディレクトリのパスに対するルートコンポーネントを定義できます。これはディレクトリ構造とフラットルーティングを混在させる際に便利です。

src/routes/
├── blog/
│   ├── route.tsx → /blog
│   ├── post.tsx → /blog/post
└── settings.route.tsx → /settings

参考

▼ TanStack Routerの命名規則についてのドキュメント

---

JISOUのメンバー募集中！

プログラミングコーチングJISOUでは、新たなメンバーを募集しています。
日本一のアウトプットコミュニティでキャリアアップしませんか？
興味のある方は、ぜひホームページをのぞいてみてくださ！
▼▼▼