🚀

Tanstack Start を Vercel にデプロイしたら404 NOT_FOUNDが出た！

に公開
React
Vercel
frontend
TanStack
tech

Tanstack Start をそのまま create して、Vercel にデプロイすると、404 エラーが表示されて詰まった。そのため、この記事では Vercel にデプロイする時の手順を説明します。

Tanstackの公式ドキュメントはこちら

同じようにエラーが出た方に貢献できたら嬉しいです。

1. プロジェクト作成

Vercel にデプロイする上でポイントとなるのが、Nitro になります。

公式ドキュメントのVercelの欄では、Nitroのデプロイメント手順に従うように案内がされています。

そのため、プロジェクトを作成時は、Select hosting provider で Nitro を選びましょう。

Nitro を選ばずにプロジェクトを開始した方も、後述の vite.config.ts に nitroV2Plugin を設定すればうまくデプロイが成功するかもしれません。私の場合はプロジェクトの途中に追加してもデプロイできました。

bun create @tanstack/start@latest

bun create @tanstack/start@latest
┌  Let's configure your TanStack Start application
│
◇  What would you like to name your project?
│  tanstack-practice
│
◇  Would you like to use Tailwind CSS?
│  Yes
│
◇  Select toolchain
│  None
│
◇  Select hosting provider
│  Nitro  ← これを選ぶ
│
◇  What add-ons would you like for your project?
│  none
│
◇  Would you like any examples?
│  none
│
◇  Initialized git repository
│
◇  Installed dependencies
│
└  Your TanStack Start app is ready in 'tanstack-practice'.

Use the following commands to start your app:
% cd tanstack-practice
% bun --bun run dev

Please read the README.md for information on testing, styling, adding routes, etc.

2. vite.config.tsにnitroの記載があるか確認

公式ドキュメントには次のように記載があります。

⚠️ @tanstack/nitro-v2-vite-plugin is a temporary compatibility plugin for using Nitro v2 as the underlying build tool for TanStack Start. Use this plugin if you experience issues with the Nitro v3 plugin. It does not support all of Nitro v3's features and is limited in its dev server capabilities, but should work as a safe fallback, even for production deployments for those who were using TanStack Start's alpha/beta versions.

日本語訳

⚠️ @tanstack/nitro-v2-vite-plugin は、 TanStack Start の基盤ビルドツールとして Nitro v2 を使用するための一時的な互換性プラグインです。Nitro v3 プラグインで問題が発生した場合は、このプラグインを使用してください。Nitro v3 のすべての機能をサポートしているわけではなく、開発サーバー機能にも制限がありますが、TanStack Start のアルファ版/ベータ版を使用していたユーザーにとって、本番環境へのデプロイでも安全なフォールバックとして機能するはずです。

プロジェクト開始時に、Select hosting provider で Nitro を選択した方は vite.config.ts ファイルが以下のようになっていることを確認しましょう。

// vite.config.ts

import tailwindcss from "@tailwindcss/vite";
import { nitroV2Plugin } from "@tanstack/nitro-v2-vite-plugin";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { defineConfig } from "vite";
import viteTsConfigPaths from "vite-tsconfig-paths";

const config = defineConfig({
  plugins: [
    nitroV2Plugin(), // ← この記載があるか確認
    // this is the plugin that enables path aliases
    viteTsConfigPaths({
      projects: ["./tsconfig.json"],
    }),
    tailwindcss(),
    tanstackStart(),
    viteReact(),
  ],
});

export default config;

既にプロジェクトを開始済みの方で、まだnitroの設定ができていない方は以下のコマンドでプラグインをインストール。

 bun add @tanstack/nitro-v2-vite-plugin

そして、上記のファイル例のように、vite.config.ts に nitroV2Plugin を追加。

3. ローカルで動作確認

bun run dev で起動して動作確認。
bun run build でビルド確認。

既にプロジェクトを開始していた方は、nitroV2Plugin を vite.config.ts に追加すると、build がタイムアウトになる可能性があります。

build が実施されない場合は、一度node_modules を削除して、再度パッケージをインストールすると、私の場合は build がうまくいきました。

build がうまくいかない場合は node_modules 削除

rm -rf node_modules

再度パッケージをインストール

bun install

再度、build

bun run build

4. Vercel にデプロイ

そのままデプロイして、無事に 404 NOT_FOUND が表示されなければ完了

初めて記事を書きました。
不正確な部分や修正点があれば教えてください。

Discussion