next CLI

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

基本的な使用方法：

npx next [command] [options]

リファレンス

以下のオプションが利用可能です：

コマンド

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

補足：コマンドなしでnextを実行すると、next devのエイリアスになります。

next devオプション

next devはHot Module Reloading（HMR）、エラー報告などを備えた開発モードでアプリケーションを起動します。next dev実行時に利用可能なオプションは以下の通りです：

next buildオプション

next buildはアプリケーションの最適化されたプロダクションビルドを作成します。出力は各ルートに関する情報を表示します。例えば：

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

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

next startオプション

next startはプロダクションモードでアプリケーションを起動します。事前にnext buildでアプリケーションをコンパイルする必要があります。

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

next infoオプション

next infoはGitHubで問題を報告する際に使用できる、現在のシステムに関する関連情報を出力します。この情報にはオペレーティングシステムのプラットフォーム/アーキテクチャ/バージョン、バイナリ（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 // 最新の利用可能なバージョンが検出されました（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コマンドで利用可能なオプションは以下の通りです：

next telemetryオプション

Next.jsは一般的な使用状況に関する完全に匿名のテレメトリデータを収集します。この匿名プログラムへの参加はオプションであり、情報の共有を希望しない場合は、オプトアウトできます。

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

詳しくはTelemetryをご覧ください。

next typegenオプション

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

以前は、ルート型はnext devまたはnext buildの実行中にのみ生成されていたため、tsc --noEmitを直接実行してもルート型は検証されませんでした。現在は、型を独立して生成し、外部で検証できます：

# まずルート型を生成し、次にTypeScriptで検証します
next typegen && tsc --noEmit
 
# またはビルドなしで型チェックを行うCI ワークフロー
next typegen && npm run type-check

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

出力ファイルは<distDir>/typesに書き込まれます（通常：.next/dev/typesまたは.next/types、isolatedDevBuildを参照）：

next typegen
# または特定のアプリの場合
next typegen ./apps/web

さらに、next typegenはnext-env.d.tsファイルを生成します。next-env.d.tsを.gitignoreファイルに追加することをお勧めします。

next-env.d.tsファイルはtsconfig.jsonファイルに含まれ、Next.js型をプロジェクトで利用可能にします。

型チェック実行前にnext typegenを実行して、next-env.d.tsが存在することを確認してください。next devおよびnext buildコマンドもnext-env.d.tsファイルを生成しますが、CI/CD環境など型チェック目的のためだけにこれらを実行することは望ましくない場合が多いです。

補足：next typegenはNext.jsのプロダクションビルドフェーズを使用して、Next.jsの設定ファイル（next.config.js、next.config.mjs、またはnext.config.ts）を読み込みます。設定が正しく読み込めるよう、必要な環境変数と依存関係が利用可能であることを確認してください。

例

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

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

next build --debug-prerender

これにより、デバッグを簡単にするために複数の試験的なオプションが有効になります：

• サーバーコードのminificationを無効にします：
  • experimental.serverMinification = false
  • experimental.turbopackMinify = false
• サーバーバンドル用のソースマップを生成します：
  • experimental.serverSourceMaps = true
• プリレンダリングに使用される子プロセスでソースマップ利用を有効にします：
  • enablePrerenderSourceMaps = true
• 最初のプリレンダリングエラー後も引き続きビルドして、すべての問題を一度に確認できます：
  • experimental.prerenderEarlyExit = false

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

警告：--debug-prerenderは開発でのデバッグのみを目的としています。--debug-prerenderで生成されたビルドをプロダクションにデプロイしないでください。パフォーマンスに悪影響を与える可能性があります。

特定のルートのビルド

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

# 特定のルートをビルド
next build --debug-build-paths="app/page.tsx"
 
# 複数のルートをビルド
next build --debug-build-paths="app/page.tsx,pages/index.tsx"
 
# グロブパターンを使用
next build --debug-build-paths="app/**/page.tsx"
next build --debug-build-paths="pages/*.tsx"

デフォルトポートの変更

デフォルトでは、開発時およびnext start時にNext.jsはhttp://localhost:3000を使用します。デフォルトポートは-pオプションで変更できます。例えば：

next dev -p 4000

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

PORT=4000 next dev

補足：PORTは.envに設定できません。HTTPサーバーのブートアップは他のコードが初期化される前に発生するためです。

開発時のHTTPSの使用

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

next dev --experimental-https

生成された証明書を使用して、Next.js開発サーバーはhttps://localhost: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を使用してローカルで信頼された証明書を作成します。プロダクションでは、信頼できる認証局から適切に発行された証明書を使用してください。

ダウンストリームプロキシのタイムアウト設定

Next.jsをダウンストリームプロキシ（たとえば、AWS ELB/ALBのようなロードバランサー）の背後にデプロイする場合、ダウンストリームプロキシのタイムアウトより大きいキープアライブタイムアウトを使用してNext.jsの基盤となるHTTPサーバーを設定することが重要です。そうしないと、指定されたTCP接続に対してキープアライブタイムアウトに達すると、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