next CLI

Next.js CLIを使用すると、アプリケーションの開発、ビルド、起動などができます。

基本的な使い方

npx next [command] [options]

リファレンス

利用可能なオプションは以下の通りです。

オプション	説明
`-h` または `--help`	利用可能なすべてのオプションを表示します。
`-v` または `--version`	Next.jsのバージョン番号を出力します。

コマンド

以下のコマンドが利用可能です。

コマンド	説明
`dev`	ホットモジュールリロード、エラーレポートなどを備えた開発モードでNext.jsを起動します。
`build`	アプリケーションの最適化された本番ビルドを作成します。各ルートに関する情報を表示します。
`start`	本番モードでNext.jsを起動します。アプリケーションは事前に`next build`でコンパイルされている必要があります。
`info`	Next.jsのバグ報告に使用できる、現在のシステムに関する関連詳細を表示します。
`telemetry`	Next.jsの完全に匿名化されたテレメトリ収集を有効または無効にできます。
`typegen`	完全なビルドを実行することなく、ルート、ページ、レイアウト、ルートハンドラーのTypeScript定義を生成します。

知っておくと良いこと: コマンドなしでnextを実行すると、next devのエイリアスになります。

`next dev`オプション

next devは、ホットモジュールリロード（HMR）、エラーレポートなどを備えた開発モードでアプリケーションを起動します。next devの実行時に以下のオプションが利用可能です。

オプション	説明
`-h, --help`	利用可能なすべてのオプションを表示します。
`[directory]`	アプリケーションをビルドするディレクトリ。指定しない場合はカレントディレクトリが使用されます。
`--turbopack`	Turbopackを強制的に有効にします（デフォルトで有効）。`--turbo`としても利用可能です。
`--webpack`	開発用に、デフォルトのTurbopackバンドラーの代わりにWebpackを使用します。
`-p`または`--port <port>`	アプリケーションを起動するポート番号を指定します。デフォルト: 3000、環境変数: PORT
`-H`または`--hostname <hostname>`	アプリケーションを起動するホスト名を指定します。ネットワーク上の他のデバイスからアプリケーションを利用可能にする場合に便利です。デフォルト: 0.0.0.0
`--experimental-https`	HTTPSでサーバーを起動し、自己署名証明書を生成します。
`--experimental-https-key <path>`	HTTPSキーファイルのパス。
`--experimental-https-cert <path>`	HTTPS証明書ファイルのパス。
`--experimental-https-ca <path>`	HTTPS認証局（CA）証明書ファイルのパス。
`--experimental-upload-trace <traceUrl>`	デバッグトレースの一部をリモートHTTP URLにレポートします。

`next build`オプション

next buildは、アプリケーションの最適化された本番ビルドを作成します。出力には各ルートに関する情報が表示されます。例:

Route (app)
┌ ○ /_not-found
└ ƒ /products/[id]
 
○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand

next buildコマンドで利用可能なオプションは以下の通りです。

オプション	説明
`-h, --help`	利用可能なすべてのオプションを表示します。
`[directory]`	アプリケーションをビルドするディレクトリ。指定しない場合はカレントディレクトリが使用されます。
`--turbopack`	Turbopackを強制的に有効にします（デフォルトで有効）。`--turbo`としても利用可能です。
`--webpack`	Webpackを使用してビルドします。
`-d`または`--debug`	より詳細なビルド出力を有効にします。このフラグを有効にすると、リライト、リダイレクト、ヘッダーなどの追加のビルド出力が表示されます。

`--profile`	本番環境のReactプロファイリングを有効にします。
`--no-lint`	リンティングを無効にします。注意: リンティングはNext 16で`next build`から削除されます。Next 15.5以降で`eslint`以外のリンターを使用している場合、ビルド中のリンティングは発生しません。
`--no-mangling`	マングリングを無効にします。これはパフォーマンスに影響を与える可能性があり、デバッグ目的でのみ使用してください。
`--experimental-app-only`	App Routerのルートのみをビルドします。
`--experimental-build-mode [mode]`	実験的なビルドモードを使用します。(選択肢: "compile", "generate", デフォルト: "default")
`--debug-prerender`	開発中のプリレンダリングエラーをデバッグします。
`--debug-build-paths=<patterns>`	デバッグ用に特定のルートのみをビルドします。

`next start`オプション

next startは、本番モードでアプリケーションを起動します。アプリケーションは事前にnext buildでコンパイルされている必要があります。

next startコマンドで利用可能なオプションは以下の通りです。

オプション	説明
`-h` または `--help`	利用可能なすべてのオプションを表示します。
`[directory]`	アプリケーションを起動するディレクトリ。ディレクトリが指定されない場合は、カレントディレクトリが使用されます。
`-p`または`--port <port>`	アプリケーションを起動するポート番号を指定します。(デフォルト: 3000、環境変数: PORT)
`-H`または`--hostname <hostname>`	アプリケーションを起動するホスト名を指定します (デフォルト: 0.0.0.0)。
`--keepAliveTimeout <keepAliveTimeout>`	非アクティブな接続を閉じる前に待機する最大ミリ秒数を指定します。

`next info`オプション

next infoは、GitHub issueを開く際に、Next.jsのバグ報告に使用できる現在のシステムに関する関連詳細を表示します。これには、オペレーティングシステム（プラットフォーム/アーキテクチャ/バージョン）、バイナリ（Node.js、npm、Yarn、pnpm）、パッケージバージョン（next、react、react-dom）などが含まれます。

出力は次のようになります。

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 23.6.0
  Available memory (MB): 65536
  Available CPU cores: 10
Binaries:
  Node: 20.12.0
  npm: 10.5.0
  Yarn: 1.22.19
  pnpm: 9.6.0
Relevant Packages:
  next: 15.0.0-canary.115 // Latest available version is detected (15.0.0-canary.115).
  eslint-config-next: 14.2.5
  react: 19.0.0-rc
  react-dom: 19.0.0
  typescript: 5.5.4
Next.js Config:
  output: N/A

next infoコマンドで利用可能なオプションは以下の通りです。

オプション	説明
`-h` または `--help`	利用可能なすべてのオプションを表示
`--verbose`	デバッグのための追加情報を収集します。

`next typegen`オプション

next typegenは、完全なビルドを実行せずに、アプリケーションのルートのTypeScript定義を生成します。これは、IDEのオートコンプリートやCIでのルート使用状況の型チェックに役立ちます。

以前は、ルート型はnext devまたはnext buildの実行中にのみ生成されていたため、tsc --noEmitを直接実行してもルート型は検証されませんでした。これで、型を個別に生成し、外部で検証できるようになりました。

# Generate route types first, then validate with TypeScript
next typegen && tsc --noEmit
 
# Or in CI workflows for type checking without building
next typegen && npm run type-check

next typegenコマンドで利用可能なオプションは以下の通りです。

オプション	説明
`-h, --help`	利用可能なすべてのオプションを表示します。
`[directory]`	型を生成するディレクトリ。指定しない場合は、カレントディレクトリが使用されます。

出力ファイルは<distDir>/typesに書き込まれます（デフォルト: .next/types）。

next typegen
# or for a specific app
next typegen ./apps/web

知っておくと良いこと: next typegenは、本番ビルドフェーズを使用してNext.jsの設定（next.config.js、next.config.mjs、またはnext.config.ts）をロードします。設定が正しくロードされるように、必要な環境変数と依存関係が利用可能であることを確認してください。

例

プリレンダリングエラーのデバッグ

next build中にプリレンダリングエラーが発生した場合、より詳細な出力を得るために--debug-prerenderフラグを渡すことができます。

next build --debug-prerender

これにより、デバッグが容易になるいくつかの実験的なオプションが有効になります。

サーバーコードのミニフィケーションを無効にします。
- experimental.serverMinification = false
- experimental.turbopackMinify = false
サーバーバンドルのソースマップを生成します。
- experimental.serverSourceMaps = true
プリレンダリングに使用される子プロセスでのソースマップの消費を有効にします。
- enablePrerenderSourceMaps = true
最初のプリレンダリングエラーが発生してもビルドを続行し、すべての問題を一度に確認できるようにします。
- experimental.prerenderEarlyExit = false

これにより、ビルド出力でより読みやすいスタックトレースとコードフレームが表示されます。

警告: --debug-prerenderは開発中のデバッグ専用です。パフォーマンスに影響を与える可能性があるため、--debug-prerenderで生成されたビルドを本番環境にデプロイしないでください。

特定のルートのビルド

--debug-build-pathsオプションを使用して、App RouterとPages Routerの特定のルートのみをビルドできます。これは、大規模なアプリケーションで作業する際に、より高速なデバッグに役立ちます。--debug-build-pathsオプションは、カンマ区切りのファイルパスを受け入れ、グロブパターンをサポートします。

# Build a specific route
next build --debug-build-paths="app/page.tsx"
 
# Build more than one route
next build --debug-build-paths="app/page.tsx,pages/index.tsx"
 
# Use glob patterns
next build --debug-build-paths="app/**/page.tsx"
next build --debug-build-paths="pages/*.tsx"

デフォルトポートの変更

デフォルトでは、Next.jsは開発中およびnext startで使用する際にhttps://:3000を使用します。デフォルトポートは、-pオプションを使用して変更できます。例:

next dev -p 4000

またはPORT環境変数を使用します。

PORT=4000 next dev

知っておくと良いこと: HTTPサーバーの起動は他のコードが初期化される前に行われるため、PORTを.envで設定することはできません。

開発中のHTTPSの使用

Webhookや認証などの特定のユースケースでは、localhostでの安全な環境のためにHTTPSを使用できます。Next.jsは、--experimental-httpsフラグを使用してnext devで自己署名証明書を生成できます。

next dev --experimental-https

生成された証明書により、Next.js開発サーバーはhttps://:3000に存在します。-p、--port、またはPORTでポートが指定されない限り、デフォルトポート3000が使用されます。

--experimental-https-keyおよび--experimental-https-certでカスタム証明書とキーを指定することもできます。オプションで、--experimental-https-caでカスタムCA証明書を指定することもできます。

next dev --experimental-https --experimental-https-key ./certificates/localhost-key.pem --experimental-https-cert ./certificates/localhost.pem

next dev --experimental-httpsは開発専用であり、mkcertでローカルに信頼される証明書を作成します。本番環境では、信頼できる認証局から発行された正規の証明書を使用してください。

下流プロキシ（例: AWS ELB/ALBなどのロードバランサー）の背後でNext.jsをデプロイする場合、Nextの基盤となるHTTPサーバーに、下流プロキシのタイムアウトよりも*大きい*keep-aliveタイムアウトを設定することが重要です。そうしないと、TCP接続のkeep-aliveタイムアウトが経過すると、Node.jsは下流プロキシに通知せずにその接続を直ちに終了します。これにより、Node.jsが既に終了した接続を再利用しようとすると、プロキシエラーが発生します。

本番環境のNext.jsサーバーのタイムアウト値を設定するには、next startに--keepAliveTimeout（ミリ秒単位）を渡します。例:

next start --keepAliveTimeout 70000

Node.js引数の渡し方

任意のnode引数をnextコマンドに渡すことができます。例:

NODE_OPTIONS='--throw-deprecation' next
NODE_OPTIONS='-r esm' next
NODE_OPTIONS='--inspect' next

バージョン	変更履歴
`v16.0.0`	JSバンドルサイズメトリクスが`next build`から削除されました。
`v15.5.0`	`next typegen`コマンドを追加します。
`v15.4.0`	`next build`に`--debug-prerender`オプションを追加し、プリレンダリングエラーのデバッグを支援します。