Turbopack バンドラー

Turbopack（JavaScript と TypeScript のために最適化されたインクリメンタルバンドラーで、Rust で書かれ Next.js に組み込まれている）のエキスパートです。Turbopack を使う際は、以下のガイドラインに従ってください。

コア原則

• Turbopack はインクリメンタルコンピュテーションとキャッシングのために設計されている
• Turbo エンジンによる関数レベルのキャッシング
• 高速ビルドのためのネイティブ Rust パフォーマンス
• TypeScript と JSX のビルトイン対応
• Next.js 統合に最適化
• Webpack 設定を抽象化

プロジェクト構成

project/
├── src/
│   ├── app/              # Next.js App Router
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   └── globals.css
│   ├── components/       # Shared components
│   └── lib/              # Utility functions
├── public/               # Static assets
├── next.config.js        # Next.js configuration
├── tsconfig.json         # TypeScript config
└── package.json

Turbopack の有効化

開発モード

# Next.js 13.4+
next dev --turbo

# または package.json で設定
{
  "scripts": {
    "dev": "next dev --turbo"
  }
}

Next.js 設定

// next.config.js
module.exports = {
  experimental: {
    turbo: {
      // Turbopack 固有の設定
    }
  }
};

設定オプション

カスタムローダー

// next.config.js
module.exports = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js'
      },
      '*.mdx': {
        loaders: ['@mdx-js/loader']
      }
    }
  }
};

Resolve エイリアス

// next.config.js
module.exports = {
  turbopack: {
    resolveAlias: {
      '@components': './src/components',
      '@lib': './src/lib',
      '@styles': './src/styles'
    }
  }
};

Resolve 拡張機能

// next.config.js
module.exports = {
  turbopack: {
    resolveExtensions: ['.tsx', '.ts', '.jsx', '.js', '.json']
  }
};

ビルトイン対応

Turbopack はビルトイン対応しています：

• TypeScript: 設定不要
• JSX/TSX: 自動変換
• CSS: ネイティブ CSS サポート
• CSS Modules: .module.css ファイル
• PostCSS: 自動処理
• 静的アセット: 画像、フォントなど

以下のローダーは不要です：

• css-loader
• postcss-loader
• babel-loader (@babel/preset-env の場合)

TypeScript 設定

推奨される tsconfig.json

{
  "compilerOptions": {
    "target": "ES2017",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

パスエイリアス

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@lib/*": ["src/lib/*"],
      "@styles/*": ["src/styles/*"]
    }
  }
}

コード構成

Atomic Design パターン

src/
├── components/
│   ├── atoms/          # 基本要素
│   │   ├── Button/
│   │   └── Input/
│   ├── molecules/      # 原子の組み合わせ
│   │   ├── SearchBar/
│   │   └── NavItem/
│   ├── organisms/      # 複雑なコンポーネント
│   │   ├── Header/
│   │   └── Footer/
│   └── templates/      # ページレイアウト
│       └── MainLayout/
├── app/
│   └── page.tsx
└── lib/
    └── utils.ts

コンポーネント構造

Button/
├── Button.tsx
├── Button.module.css
├── Button.test.tsx
└── index.ts

コード分割

動的インポート

import dynamic from 'next/dynamic';

const HeavyComponent = dynamic(() => import('@/components/HeavyComponent'), {
  loading: () => <p>Loading...</p>,
  ssr: false // 必要に応じてサーバーサイドレンダリングを無効化
});

ルートベースの分割

Next.js は app/ ディレクトリ内のルートごとに自動的にコード分割されます。

手動分割

// 大きなコンポーネントを分割
const ChartComponent = dynamic(() => import('./ChartComponent'));
const EditorComponent = dynamic(() => import('./EditorComponent'));

キャッシング戦略

Turbo エンジンキャッシング

• インクリメンタルビルドのための関数レベルキャッシング
• 変更箇所のみを再計算
• ビルド全体で永続的なキャッシュ

キャッシュの最適化

// モジュールはフォーカスして小さく保つ
// 1 つのモジュールへの変更は他のモジュールを無効化しない

// 良い例: 関心の分離
export function formatDate(date: Date) { /* ... */ }
export function formatCurrency(amount: number) { /* ... */ }

// 避けるべき: 頻繁に変更される大きなユーティリティファイル

パフォーマンスのベストプラクティス

モジュール構成

• モジュールは小さくフォーカスされたまま保つ
• モジュール間の依存関係を最小化
• バレルエクスポートは控えめに使う

インポート最適化

// 特定のインポートを優先
import { Button } from '@/components/Button';

// ライブラリ全体のインポートを避ける
// 悪い例: import _ from 'lodash';
// 良い例: import debounce from 'lodash/debounce';

静的解析

// より良いツリーシェイキングのために const アサーションを使用
const ROUTES = {
  home: '/',
  about: '/about',
  contact: '/contact'
} as const;

CSS 処理

CSS Modules

import styles from './Component.module.css';

function Component() {
  return <div className={styles.container}>Content</div>;
}

グローバル CSS

// app/layout.tsx
import './globals.css';

Tailwind CSS

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './app/**/*.{js,ts,jsx,tsx,mdx}'
  ]
};

環境変数

Next.js 環境変数

# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com
DATABASE_URL=postgresql://...

// クライアント側（NEXT_PUBLIC_ プレフィックスが必須）
const apiUrl = process.env.NEXT_PUBLIC_API_URL;

// サーバー側のみ
const dbUrl = process.env.DATABASE_URL;

テスト

テスト構成

src/
├── components/
│   └── Button/
│       ├── Button.tsx
│       └── Button.test.tsx    # コロケーションテスト
└── __tests__/                 # 統合テスト
    └── pages/
        └── home.test.tsx

テストのベストプラクティス

• ユーティリティ関数のユニットテストを作成
• コンポーネントは React Testing Library を使用
• E2E テストは Cypress または Playwright で実施
• テストはテストするコードの近くに保つ

よくある落とし穴

設定の問題

// tsconfig.json パスが正しいことを確認
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]  // 実際の構造と一致する必要がある
    }
  }
}

キャッシングの問題

# 問題が発生した場合 Turbopack キャッシュをクリア
rm -rf .next

互換性

• Turbopack との依存関係互換性を確認
• 一部の Webpack プラグインは直接動作しない場合がある
• webpack 設定の代わりに Next.js 設定を使用

Webpack からのマイグレーション

変わること

• 直接的な webpack.config.js はない
• カスタマイズに next.config.js を使用
• 一部のローダーは Turbopack 同等物が必要

変わらないこと

• インポート構文
• 動的インポート
• CSS Modules
• TypeScript 対応

ベストプラクティスまとめ

すべきこと

• カスタマイズに Next.js 設定を使用
• ビルトイン TypeScript と JSX サポートを活用
• インクリメンタルコンピュテーション向けにコードを構成
• コード分割に動的インポートを使用
• モジュールはフォーカスして小さく保つ

すべきでないこと

• 直接的な webpack 設定
• 頻繁に変更される大きなバレルファイル
• Next.js 慣例に逆らう
• TypeScript パス設定を無視

デバッグ

詳細ログ

NEXT_DEBUG_TURBOPACK=1 next dev --turbo

ビルド分析

# ビルド出力を確認
ANALYZE=true next build

よくある問題

1. 初回ビルドが遅い: 正常な動作で、以降のビルドは高速
2. モジュールが見つからない: tsconfig.json でパスエイリアスを確認
3. CSS が読み込まれない: インポート構文が正しいことを確認
4. 型エラー: 別途 tsc --noEmit を実行