Next.jsの環境構築沼から、Next.js Enterprise Boilerplateで抜け出した

はじめに

新しくNext.jsのプロジェクトを始めるたびに、ESLintとPrettierの設定を書き直し、テスト環境を一から組み立て、CI/CDのワークフローを整備し直す……という作業に時間を取られていないでしょうか。個人開発ならまだしも、チームで長く運用するプロダクトになると、こうした「土台づくり」の品質がそのままプロジェクトの保守性に直結します。

Next.js Enterprise Boilerplateは、まさにこの土台づくりを最初から済ませてくれるスターターテンプレートです。本記事では、その特徴と実際の使い方を紹介します。

Next.js Enterprise Boilerplateとは

Next.js Enterprise Boilerplateは、Blazity社が公開している、本番運用を前提としたNext.jsのボイラープレートです。GitHub上で7,000を超えるStarを集めており、「戦略的シンプリシティ（Strategic Simplicity）」を掲げ、過剰な抽象化を避けながらも企業レベルの品質を最初から備える設計を特徴としています。

単なるサンプルコードの寄せ集めではなく、コード品質、テスト、CI/CD、可観測性まで含めて「そのまま本番に持っていける」構成になっている点が、数あるNext.jsテンプレートの中でも評価されている理由です。

主な特徴

• モダンな技術スタック - Next.js 15（App Router）、Tailwind CSS v4、厳格な設定のTypeScriptを標準採用
• 充実したテスト環境 - Vitest・React Testing Library・Playwrightがあらかじめ組み込み済みで、ユニットテストからE2Eテストまでカバー
• コンポーネント開発基盤 - Radix UIとCVA（Class Variance Authority）を使ったヘッドレスコンポーネント設計、Storybookによるカタログ化
• 自動化されたCI/CD - GitHub Actionsによるバンドルサイズ・パフォーマンス計測付きのワークフローが最初から用意されている
• 可観測性への配慮 - OpenTelemetryによるトレーシングや、Kubernetes向けのヘルスチェックエンドポイントも標準搭載
• 依存関係の自動更新 - Renovate BOTとSemantic Releaseにより、パッケージ更新とリリース作業の手間を削減

インストール

Next.js Enterprise Boilerplateはnpmパッケージではなく、GitHubのテンプレートリポジトリとして提供されています。GitHub上の「Use this template」ボタンから新規リポジトリを作成するか、直接クローンして始められます。

# GitHubの「Use this template」で作成したリポジトリをクローン
git clone https://github.com/your-username/your-project.git
cd your-project

# corepackを有効化してpnpmを使う
corepack enable
pnpm install

# 開発サーバーを起動
pnpm dev

Vercelへのワンクリックデプロイボタンも公式リポジトリに用意されているため、動作確認だけならクローンせずに試すこともできます。

基本的な使い方

セットアップが完了すると、以下のようなディレクトリ構成でプロジェクトが立ち上がります。

.
├── app/                # Next.js App Router
├── components/         # UIコンポーネント（Radix UI + CVA）
├── stories/            # Storybook用ストーリー
├── e2e/                # Playwrightによるe2eテスト
├── .github/workflows/  # CI/CDワークフロー定義
└── next.config.js

日常的な開発で使うコマンドは以下の通りです。

pnpm dev         # 開発サーバー起動
pnpm build       # 本番ビルド
pnpm test        # Vitestによるユニットテスト
pnpm test:e2e    # Playwrightによるe2eテスト
pnpm storybook   # Storybookの起動
pnpm lint        # ESLintによる静的解析

create-next-appで作った直後のプロジェクトと違い、この時点ですでにテストランナー・Lint設定・CIワークフローが動く状態になっているのが最大の違いです。

このライブラリはNode.js上で動くプロジェクトテンプレートであり、ブラウザ単体で完結するライブラリではないため、本記事ではブラウザ実行サンプル（LiveCodes）の代わりに、実際のコード例で使い方を紹介します。

実践的なユースケース

CVAでUIコンポーネントのバリアントを管理する

ボタンのサイズや色といったバリエーションをif文やクラス名の文字列結合で管理すると、コンポーネントが肥大化しがちです。Next.js Enterprise BoilerplateではCVA（Class Variance Authority）を使い、バリアントを宣言的に定義します。

// components/button.tsx
import { cva, type VariantProps } from "class-variance-authority"

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md font-medium transition-colors",
  {
    variants: {
      variant: {
        primary: "bg-blue-600 text-white hover:bg-blue-700",
        outline: "border border-gray-300 text-gray-900 hover:bg-gray-50",
      },
      size: {
        sm: "h-8 px-3 text-sm",
        md: "h-10 px-4 text-base",
      },
    },
    defaultVariants: {
      variant: "primary",
      size: "md",
    },
  }
)

type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> &
  VariantProps<typeof buttonVariants>

export function Button({ variant, size, className, ...props }: ButtonProps) {
  return (
    <button className={buttonVariants({ variant, size, className })} {...props} />
  )
}

<Button variant="outline" size="sm" />のように呼び出すだけで、バリアントの組み合わせに応じたクラス名が型安全に生成されます。

Playwrightでe2eテストを書く

テスト環境がすでに整っているため、主要な導線のe2eテストを追加するだけですぐに動かせます。

// e2e/home.spec.ts
import { test, expect } from "@playwright/test"

test("トップページが表示され、見出しが確認できる", async ({ page }) => {
  await page.goto("/")
  await expect(page.getByRole("heading", { level: 1 })).toBeVisible()
})

pnpm test:e2eを実行すれば、ローカルで起動したアプリに対してブラウザ操作を伴うテストが走ります。

GitHub Actionsのワークフローをカスタマイズする

標準のCIには、Lint・テスト・バンドルサイズ計測が含まれていますが、プロジェクトに合わせて拡張することも簡単です。

# .github/workflows/ci.yml（抜粋）
name: CI

on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - run: pnpm install
      - run: pnpm lint
      - run: pnpm test
      - run: pnpm build

既存のワークフローに- run: pnpm test:e2eのようなステップを追加するだけで、E2Eテストもプルリクエスト単位で自動実行できます。

OpenTelemetryで可観測性を確保する

本番運用では「エラーが起きたときに何が起きたか追える状態」が重要です。Next.js Enterprise BoilerplateにはOpenTelemetryの設定が含まれており、以下のようにインストルメンテーションを拡張できます。

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { registerOTel } = await import("@vercel/otel")
    registerOTel({ serviceName: "my-next-app" })
  }
}

Next.jsのinstrumentation.tsはサーバー起動時に一度だけ実行されるため、トレーシングやログ基盤との接続をここに集約しておくと、あとから監視ツールを差し替える際も変更箇所を最小限に抑えられます。

まとめ

Next.js Enterprise Boilerplateは、「とりあえず動くNext.jsアプリ」ではなく、「チームで長期運用できるNext.jsアプリ」の土台を最初から提供してくれるテンプレートです。テスト・CI/CD・可観測性・依存関係管理といった、後回しにされがちな部分がすでに組み込まれているため、プロジェクトの立ち上げ直後から本質的な機能開発に集中できます。

新規プロジェクトの初期構築に時間を取られていると感じたら、一度テンプレートとして採用し、必要な部分だけ自分のプロジェクトに合わせてカスタマイズしていくのがおすすめです。

参考リンク

• Next.js Enterprise Boilerplate公式ドキュメント
• Next.js Enterprise Boilerplate GitHub
• @next/bundle-analyzer - npm