【2025年最新】pnpmとTurbopackで構築するNext.jsプロジェクト開発

はじめに

Next.jsは現在、フロントエンド開発における最も人気のあるメタフレームワークです。この記事では、効率的な依存関係管理が可能なpnpmと、高速な開発環境を提供するTurbopackを組み合わせたNext.jsプロジェクトの構築方法について調査し実際に構築した内容をもとに解説します。

環境準備

pnpmをグローバルにインストールしていない場合は、まず次のコマンドでインストールします：

npm install -g pnpm

Voltaなどのバージョン管理ツールを使用している場合は、自動的に適切なバージョンがインストールされます。

プロジェクト作成の基本手順

1. プロジェクトの初期化

pnpm create next-app@latest my-project-name

初期設定では以下のような選択肢が表示されます：

✔ Would you like to use TypeScript? … Yes
✔ Would you like to use ESLint? … Yes 
✔ Would you like to use Tailwind CSS? … Yes
✔ Would you like to use `src/` directory? … Yes
✔ Would you like to use App Router? … Yes
✔ Would you like to use Turbopack for `next dev`? … Yes/No
✔ Would you like to customize the default import alias (@/*)? … Yes

「Would you like to use Turbopack for next dev?」について：

• 「Yes」を選択すると、開発サーバーがTurbopackを使用するようになります
• Turbopackは従来のWebpackと比較して大幅に開発速度が向上し、開発サーバーの起動やコード更新が高速化されるメリットがあります
• ただし、プロジェクトの要件や既存の設定によっては従来のWebpackを選択する理由もあるかもしれません

2. pnpmのビルドスクリプト警告対応

プロジェクト作成後や追加パッケージのインストール時に、次のような警告が表示される場合があります：

╭ Warning ──────────────────────────────────────────────────────────────────────────────────╮
│                                                                                           │
│   Ignored build scripts: sharp, unrs-resolver, esbuild.                                   │
│   Run "pnpm approve-builds" to pick which dependencies should be allowed to run           │
│   scripts.                                                                                │
│                                                                                           │
╰───────────────────────────────────────────────────────────────────────────────────────────╯

この警告は、pnpm v10以降ではセキュリティ強化のため、デフォルトでパッケージのビルドスクリプトが制限されることによるものです。これらのパッケージは重要な機能を提供するため、ビルドスクリプトを実行する必要があります：

• sharp: Next.jsの画像最適化機能に必要
• esbuild: 高速なJavaScriptバンドラーで、多くの開発ツールの基盤として使用されています
• unrs-resolver: Next.jsのリソース解決に使用

解決方法としては：

方法1: 直接ビルドスクリプトを実行する（シンプルな解決策）

プロジェクトディレクトリで以下のコマンドを実行します：

pnpm rebuild

このコマンドは警告されていたパッケージのビルドスクリプトを実行します。次のような出力が表示されれば成功です：

node_modules/.pnpm/sharp@0.34.1/node_modules/sharp: Running install script, done in 3.4s
node_modules/.pnpm/unrs-resolver@1.6.1/node_modules/unrs-resolver: Running postinstall script, done in 312ms
node_modules/.pnpm/esbuild@x.x.x/node_modules/esbuild: Running install script, done in xxx ms

方法2: package.jsonに設定を追加する（恒久的な解決策）

チーム開発や継続的インテグレーション環境でも同じ問題が発生しないようにするには、package.jsonに以下の設定を追加します：

{
  "pnpm": {
    "onlyBuiltDependencies": [
      "sharp",
      "unrs-resolver",
      "esbuild"
    ]
  }
}

設定を追加した後、pnpm rebuildを実行して変更を適用します。

3. プロジェクトディレクトリに移動

cd my-project-name

4. 追加パッケージのインストール（オプション）

プロジェクトの要件に応じて、以下のような追加パッケージのインストールを検討できます：

状態管理とデータフェッチング（オプション）

# 状態管理
pnpm add zustand  # 軽量な状態管理ライブラリ

# API通信
pnpm add @tanstack/react-query  # データフェッチングと状態管理

# フォーム関連
pnpm add react-hook-form zod @hookform/resolvers  # フォーム管理とバリデーション

UI関連パッケージ（オプション）

pnpm add class-variance-authority  # 条件付きクラス生成
pnpm add clsx  # クラス名の結合ユーティリティ
pnpm add tailwind-merge  # Tailwindクラスの重複解決
pnpm add lucide-react  # アイコンライブラリ

開発ツール（推奨）

pnpm add -D prettier  # コードフォーマッター
pnpm add -D vitest @testing-library/react  # テストフレームワーク
pnpm add -D husky lint-staged  # Git連携とコミット前検証

パッケージを追加した後に同様のビルドスクリプト警告が表示された場合は、前述の方法で対応してください。

5. Gitセットアップとコミット前検証の構成（オプション）

コード品質を維持するためのGitフックを設定する場合、Husky v9の最新の方法を使用します：

# Huskyの初期化（v9の新しい方法）
pnpm dlx husky init

このコマンドは、.huskyディレクトリを作成し、package.jsonにprepareスクリプトを追加します。次に、pre-commitフックを設定します：

# pre-commitフックにlint-stagedを追加
echo "npx lint-staged" > .husky/pre-commit

package.jsonに以下を追加します：

"lint-staged": {
  "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
  "*.{json,css,md}": ["prettier --write"]
}

注意: Husky v9では以前のpnpm dlx husky add .husky/pre-commit "pnpm lint-staged"方式は非推奨となりました。上記の方法が推奨されています。

6. UIコンポーネントライブラリのセットアップ（オプション）

ShadCN UIは最近ウェブサイトを更新し、CLIライブラリ名を変更したため、以前のshadcn-uiコマンドは非推奨となりました。代わりにshadcnパッケージを使用します：

# 最新のshadcnパッケージを使用（shadcn-uiは非推奨）
pnpm dlx shadcn@latest init

設定の初期化後、必要なコンポーネントをプロジェクトに追加できます：

# 例：ボタンコンポーネントの追加
pnpm dlx shadcn@latest add button

最新のshadcnセットアップでは、tailwindcss-animateの代わりにtw-animate-cssが使用されるようになりました。インストール時に自動的に設定されなかった場合は、手動でインストールしてCSSファイルを更新する必要があります。

# アニメーションライブラリをインストール
pnpm add -D tw-animate-css

そしてglobals.cssに以下を追加します：

@import "tw-animate-css";

React 19との互換性

React 19ではforwardRef関数が非推奨となっており、最新のshadcnコンポーネントはReact 19に対応するよう、forwardRefを使用する代わりにrefを通常のpropとして受け取る形式に更新されています。

新しいプロジェクトを作成する場合、Tailwind v4とReact 19に対応した最新のコンポーネントが使用されますが、既存のプロジェクトでは古いバージョンが動作し続けます。

推奨ディレクトリ構造

Next.jsのApp Routerを活用した2025年現在の一般的なディレクトリ構造は以下の通りです：

my-project/
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   └── [...]/
│   │   │       └── route.ts
│   │   ├── (auth)/
│   │   │   └── [...]/
│   │   │       └── page.tsx
│   │   ├── (dashboard)/
│   │   │   └── [...]/
│   │   │       └── page.tsx
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── components/
│   │   ├── ui/             # 基本UIコンポーネント
│   │   ├── layout/         # レイアウト関連コンポーネント
│   │   └── feature/        # 機能特化コンポーネント
│   ├── hooks/              # カスタムフック
│   ├── lib/                # ユーティリティ関数
│   ├── services/           # APIとの通信ロジック
│   ├── stores/             # 状態管理
│   └── types/              # 型定義
├── public/                 # 静的ファイル
├── middleware.ts           # Next.jsミドルウェア
├── next.config.js
├── package.json
└── tsconfig.json

テスト環境のセットアップ（オプション）

Vitestを使用してテスト環境を設定することができます。Vitestの最新バージョンは3.1.1で、この投稿の約3週間前にリリースされました。

プロジェクトのルートディレクトリにvitest.config.tsファイルを手動で作成します：

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    environment: 'node', // または 'jsdom'（React用）
    // グローバルテストAPIを有効にする場合（Jest互換性向上）
    // globals: true,
  },
})

package.jsonにテスト用のスクリプトを追加：

{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run"
  }
}

React Testing Libraryを使用する場合は追加のパッケージをインストールします：

pnpm add -D @testing-library/react @testing-library/jest-dom jsdom

テストファイルは一般的に2つの方法で配置できます：

1. コンポーネントと同じディレクトリに配置する（Button.tsxと同じ場所にButton.test.tsx）
2. 専用のテストディレクトリを作成する（__tests__/components/Button.test.tsx）

コンポーネントとの関連性を明確にするため、特に理由がなければコンポーネントと同じディレクトリにテストファイルを配置することをお勧めします。

開発サーバーの起動

Next.jsの開発サーバーを起動します：

pnpm dev

これでhttp://localhost:3000にアクセスできます。Turbopackを選択した場合、従来のWebpackと比較して高速なHot Module Replacement (HMR)と開発体験が得られます。

ビルドと本番デプロイ

# 通常のビルド
pnpm build

# または、Turbopackを使ったビルド（2025年4月時点ではアルファ版）
pnpm build --turbo

# 本番サーバー起動
pnpm start

2025年4月現在、build --turboはアルファ版ですが、テストの99%以上に合格しており、ステージング環境などでの検証に適しています。

Vercelへのデプロイ（オプション）

pnpm dlx vercel

最新の技術スタック (2025年現在)

• フレームワーク: Next.js（App Router + オプションでTurbopack）
• 言語: JavaScript/TypeScript
• パッケージマネージャー: pnpm
• スタイリング: Tailwind CSS v4
• 状態管理: Zustand/Jotai/Redux Toolkit (プロジェクトに応じて選択)
• APIクライアント: TanStack Query/SWR (プロジェクトに応じて選択)
• テスト: Vitest + Testing Library/Playwright (プロジェクトに応じて選択)
• コード品質: ESLint + Prettier
• UIコンポーネント: shadcn (new-yorkスタイル、以前のshadcn-uiに替わるもの)

まとめ

この記事では、pnpmとNext.jsを使用したモダンなWebアプリケーション開発の基本的な流れを紹介しました。Turbopackの採用やさまざまなパッケージの選択は、プロジェクトの要件に応じて判断することが重要です。

pnpm v10でのビルドスクリプト警告への対応方法や、Husky v9での最新のGitフック設定方法、shadcnへのパッケージ名変更など、最新の変更点も含めて調査しました。また、React 19とTailwind v4との互換性についても触れました。

Next.jsの技術は進化を続けているため、公式ドキュメントを定期的に確認することをお勧めします。この記事がのNext.jsプロジェクト構築の参考になれば幸いです。