React RouterのuseNavigateで出るエラーの直し方

​​React​React Router,TypeScript,Vite,Vitest,トラブルシュート

React Router の useNavigate() を呼んだコンポーネントが、<BrowserRouter> や <RouterProvider> の内側に入っていないと、コンソールに useNavigate() may be used only in the context of a <Router> component. というエラーが出て、画面が真っ白になります。useNavigate() は、ボタンを押したら一覧ページへ移る、ログインのあとでトップページへ戻す、のようにプログラムからページを移動させる(画面遷移させる)ときに使うフックです。呼んだコンポーネントを Router の内側に移すか、Router をもっと外側に移すと、エラーは消えます。react-router-dom と react-router を混ぜて import しているときは、import を react-router に揃えると消えます。

私は検証環境で、このエラーが出る3つの場合と、テストで出る場合を実際に起こし、直すと消えることを確かめました。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4 です。npm create vite@latest の react-ts テンプレートで作ったプロジェクト(React 19.3.1、Vite 8.3.8、TypeScript 7.0.2)に React Router 8.5.1 を入れ、コンポーネントを StrictMode で囲んで試しました。混ぜたときの検証には react-router-dom 7.18.5、テストには Vitest 5.1.0、jsdom 31.0.0、Testing Library 16.3.3 を使いました。ページは Chromium 153 を Playwright 1.63.0 で操作して開き、DevTools の画面は、画面ありの Chromium を仮想ディスプレイ(Xvfb)で動かして撮りました。React Router のフレームワークモード、サーバーでの描画、Jest、Chromium 以外のブラウザーは試していません。

コンソールに出るエラーの全文

Vite の開発サーバーで、Router の外で useNavigate() を呼んだページを開くと、コンソールには次のエラーが出ました。

text
Uncaught Error: useNavigate() may be used only in the context of a <Router> component.

続けて、エラーが起きたコンポーネントの名前が入った警告も出ます。

text
An error occurred in the <Header> component.

Consider adding an error boundary to your tree to customize error handling behavior.
Visit https://react.dev/link/error-boundaries to learn more about error boundaries.
DevTools のコンソールに、赤い行で「Uncaught Error: useNavigate() may be used only in the context of a <Router> component.」と「at Header (Header.tsx:4:20)」、黄色い行で「An error occurred in the <Header> component.」が出ている。上のページには何も表示されていない
Router の外に置いた Header で useNavigate を呼んだページを開いたところ

エラーの文は「useNavigate() は <Router> の内側でしか使えない」という意味です。DevTools では、エラーの下に at Header (Header.tsx:4:20) と出ていて、useNavigate() を呼んだコンポーネントとファイルの行が分かります。ページは真っ白で、コンポーネントを入れる <div id="root"> の中は空でした。

React Router のソースコードでは、useNavigate から呼ばれる判定(useNavigateUnstable)が見ているのは、親をたどった先に Router があるかどうかだけです(Router が用意する context があるかで調べています)。Router がなければ、この文のエラーを投げます。<BrowserRouter> も <RouterProvider> も Router に当たるので、どちらを使っていても同じ文が出ます。

App の中で BrowserRouter を返している

いちばん起こしやすいのは、<BrowserRouter> を返すコンポーネントの中で、そのまま useNavigate() を呼んでしまう書き方です。

tsx
import { BrowserRouter, Route, Routes, useNavigate } from 'react-router';

// まちがい:BrowserRouter を返すコンポーネントの中で useNavigate を呼んでいる
export default function BadApp() {
  const navigate = useNavigate();
  return (
    <BrowserRouter>
      <button onClick={() => navigate('/cats')}>猫の一覧へ</button>
      <Routes>
        <Route path="/" element={<p>トップ</p>} />
        <Route path="/cats" element={<p>猫の一覧</p>} />
      </Routes>
    </BrowserRouter>
  );
}

コードの見た目では、ボタンは <BrowserRouter> の中にあります。しかし useNavigate() を呼んでいるのは BadApp 自身で、BadApp は <BrowserRouter> の外側(親)です。検証では、ページを開いた時点でエラーになり、警告には An error occurred in the <BadApp> component. と出ました。

直すには、<BrowserRouter> を main.tsx に移して、App を外側から包みます。公式ドキュメントのモードの説明にある例も、この形です。検証用の main.tsx は、ページの URL で描画するものを切り替える作りにしましたが、この場合に描画しているのは次のコードと同じです。

tsx
// main.tsx
createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <BrowserRouter>
      <GoodApp />
    </BrowserRouter>
  </StrictMode>,
)
tsx
import { Route, Routes, useNavigate } from 'react-router';

// 直したもの:BrowserRouter は main.tsx で外側に置き、App の中では useNavigate だけを使う
export default function GoodApp() {
  const navigate = useNavigate();
  return (
    <>
      <button onClick={() => navigate('/cats')}>猫の一覧へ</button>
      <Routes>
        <Route path="/" element={<p>トップ</p>} />
        <Route path="/cats" element={<p>猫の一覧</p>} />
      </Routes>
    </>
  );
}

直したページではエラーが出ず、「トップ」が表示されました。ボタンを押すと、URL のパスが /cats に変わり、表示が「猫の一覧」に変わりました。

ヘッダーを RouterProvider の横に置いている

createBrowserRouter と <RouterProvider> で書くデータモードでは、全ページに出すヘッダーを <RouterProvider> と並べて置くと、このエラーになります。次の Header は、ボタンで一覧ページへ移るだけのコンポーネントです。

tsx
import { useNavigate } from 'react-router';

export default function Header() {
  const navigate = useNavigate();
  return (
    <header>
      <button onClick={() => navigate('/cats')}>猫の一覧へ</button>
    </header>
  );
}
tsx
import { createBrowserRouter } from 'react-router';
import { RouterProvider } from 'react-router/dom';
import Header from './Header';

const router = createBrowserRouter([
  { path: '/', element: <p>トップ</p> },
  { path: '/cats', element: <p>猫の一覧</p> },
]);

// まちがい:Header を RouterProvider の外(横)に置いている
export default function DataBad() {
  return (
    <>
      <Header />
      <RouterProvider router={router} />
    </>
  );
}

Header は <RouterProvider> の中ではなく横にあるので、Router の外です。さきほどの画像は、このページを開いたところです。

データモードで <RouterProvider> の内側に入るのは、createBrowserRouter のルートに書いた要素(element)だけです。ヘッダーのように全ページに出すものは、path を書かない親ルート(公式ドキュメントでいうレイアウトルート)を作り、そのコンポーネントの中に置きます。各ページは、親ルートのコンポーネントに置いた <Outlet /> の位置に表示されます。

tsx
import { Outlet, createBrowserRouter } from 'react-router';
import { RouterProvider } from 'react-router/dom';
import Header from './Header';

// 直したもの:Header を、すべてのページを包むルート(レイアウト)の中に入れる
function Layout() {
  return (
    <>
      <Header />
      <Outlet />
    </>
  );
}

const router = createBrowserRouter([
  {
    element: <Layout />,
    children: [
      { path: '/', element: <p>トップ</p> },
      { path: '/cats', element: <p>猫の一覧</p> },
    ],
  },
]);

export default function DataGood() {
  return <RouterProvider router={router} />;
}

直したページでは、ヘッダーのボタンの下に「トップ」が表示され、エラーは出ませんでした。ボタンを押すと、URL のパスが /cats になり、表示が「猫の一覧」に変わりました。

ページに「猫の一覧へ」のボタンと「猫の一覧」が表示され、アドレスバーは localhost:5173/cats。下の DevTools のコンソールには、React DevTools の案内の1行だけが出ている
Header をレイアウトのルートに入れて、ボタンを1回押したところ。エラーは出ていない

react-router-dom と react-router を混ぜて import している

Router の内側に置いているのに、このエラーが出ることもあります。検証では、<BrowserRouter> を react-router-dom から、useNavigate を react-router から import したときに出ました。

tsx
import { BrowserRouter } from 'react-router-dom';
import Header from './Header';

// まちがい:BrowserRouter は react-router-dom から、useNavigate(Header の中)は react-router から import している
export default function MixedBad() {
  return (
    <BrowserRouter>
      <Header />
    </BrowserRouter>
  );
}

このとき、プロジェクトには React Router 8.5.1 と、react-router-dom 7.18.5 を入れていました。npm ls react-router を実行すると、react-router-dom の下に、もう1つ別のバージョンの react-router が入っていました(パスは例示用の値に置き換えています)。

text
app@0.0.0 /path/to/app
+-- react-router-dom@7.18.5
| `-- react-router@7.18.5
`-- react-router@8.5.1

React Router が2つ入っていると、<BrowserRouter> が用意する Router の情報と、useNavigate() が探しにいく Router の情報(React の context)が、別々のものになります。そのため useNavigate() からは、外側に Router がないように見えます。Vite が事前バンドルしたファイルを見ても、react-router 8.5.1 のコードと、react-router-dom の下の react-router 7.18.5 のコードが、別のファイルに入っていました。React Router のソースコードでも、useNavigate のこのエラーの箇所に、開発者向けの TODO として「このエラーはおそらく、なんらかの理由で React Router の2つのバージョンが読み込まれているのが原因だ」という趣旨のコメントがあります。

React Router 8 では、react-router-dom のパッケージがなくなりました。公式の v7 からの移行ガイドには、npm uninstall react-router-dom でアンインストールし、import を react-router に置き換えるように書かれています。RouterProvider のような DOM 向けのものは react-router/dom から import します。検証では、BrowserRouter の import を react-router に揃えたところ、エラーは出なくなり、ボタンを押すと URL のパスが /cats に変わりました。

テストで出るときは MemoryRouter で包む

アプリでは正しく動いていても、useNavigate() を使うコンポーネントを、テストで単体のまま描画すると同じエラーになります。Vitest と Testing Library で、Header を2通りに描画しました。

tsx
import { render, screen } from '@testing-library/react';
import { MemoryRouter } from 'react-router';
import { expect, test } from 'vitest';
import Header from '../cases/Header';

// まちがい:Router で包まずに描画している
test('Router で包まずに描画する', () => {
  render(<Header />);
  expect(screen.getByRole('button', { name: '猫の一覧へ' })).toBeTruthy();
});

// 直したもの:MemoryRouter で包んで描画する
test('MemoryRouter で包んで描画する', () => {
  render(
    <MemoryRouter>
      <Header />
    </MemoryRouter>,
  );
  expect(screen.getByRole('button', { name: '猫の一覧へ' })).toBeTruthy();
});

npx vitest run を実行すると、包まなかったテストだけが失敗しました(抜粋)。

text
 FAIL  src/test/Header.test.tsx > Router で包まずに描画する
Error: useNavigate() may be used only in the context of a <Router> component.
 ❯ invariant node_modules/react-router/dist/development/lib/router/history.js:189:79
 ❯ useNavigateUnstable node_modules/react-router/dist/development/lib/hooks.js:272:2
 ❯ useNavigate node_modules/react-router/dist/development/lib/hooks.js:269:72
 ❯ Header src/cases/Header.tsx:4:20
text
      Tests  1 failed | 1 passed (2)

MemoryRouter は、移動の履歴をブラウザーではなくメモリーの中に持つ Router です。検証では、テストで Header をこれで包むだけで、エラーが出なくなりました。

型チェックでは見つからず、本番用のビルドでも同じ文が出る

ここまでのまちがいは、どれも型としては正しいので、npx tsc -p tsconfig.app.json --noEmit ではエラーになりませんでした。テンプレートに入っている lint ツールの oxlint(npx oxlint src)も、何も出しませんでした。ブラウザーで開くか、テストで描画するまで気づけません。

npx vite build で本番用にビルドして開いた場合も、エラーの文は開発サーバーのときと同じ useNavigate() may be used only in the context of a <Router> component. でした。ただし、スタックに出る関数の名前は C のように縮められていて、コンポーネントの名前が入った警告(An error occurred in the <…> component.)も出なかったため、どのコンポーネントで起きたかは分かりませんでした。本番で出たときは、開発サーバーで同じページを開いて、DevTools に出るコンポーネントの名前とファイルの行を確かめます。

​Posted by 86