output

ビルド時に、Next.jsは各ページとその依存関係を自動的にトレースし、アプリケーションの本番環境デプロイに必要なすべてのファイルを決定します。

この機能により、デプロイサイズを大幅に削減できます。以前はDockerでデプロイする際、next startを実行するためにパッケージのdependenciesにあるすべてのファイルをインストールする必要がありました。Next.js 12以降では、.next/ディレクトリ内のOutput File Tracingを利用して必要なファイルのみを含めることができます。

さらに、これにより非推奨のserverlessターゲットが不要になり、様々な問題や不必要な重複を解消できます。

仕組み

next build中、Next.jsは@vercel/nftを使用してimport、require、fsの使用状況を静的に分析し、ページが読み込む可能性のあるすべてのファイルを決定します。

Next.jsの本番サーバーも必要なファイルがトレースされ、.next/next-server.js.nft.jsonに出力されます。これは本番環境で活用できます。

.next出力ディレクトリに出力された.nft.jsonファイルを活用するには、各トレース内のファイルリスト（.nft.jsonファイルからの相対パス）を読み取り、デプロイ先にコピーします。

トレースされたファイルの自動コピー

Next.jsはnode_modules内の選択されたファイルを含め、本番デプロイに必要なファイルのみをコピーするstandaloneフォルダを自動的に作成できます。

この自動コピー機能を利用するには、next.config.jsで有効にします：

module.exports = {
  output: 'standalone',
}

これにより.next/standaloneフォルダが作成され、node_modulesをインストールせずに単独でデプロイ可能になります。

さらに、最小限のserver.jsファイルも出力され、next startの代わりに使用できます。この最小サーバーはデフォルトでpublicや.next/staticフォルダをコピーしません（これらは理想的にはCDNで処理されるべきですが）、手動でstandalone/publicとstandalone/.next/staticフォルダにコピーした後、server.jsファイルが自動的にこれらを提供します。

手動でコピーするには、next build後にcpコマンドラインツールを使用します：

cp -r public .next/standalone/ && cp -r .next/static .next/standalone/.next/

ローカルで最小server.jsファイルを起動するには、次のコマンドを実行します：

node .next/standalone/server.js

知っておくと便利:

• next.config.jsはnext build中に読み込まれ、server.js出力ファイルにシリアライズされます。レガシーなserverRuntimeConfigまたはpublicRuntimeConfigオプションを使用している場合、値はビルド時の値に固定されます。
• プロジェクトが特定のポートやホスト名をリッスンする必要がある場合、server.jsを実行する前にPORTまたはHOSTNAME環境変数を定義できます。例えば、PORT=8080 HOSTNAME=0.0.0.0 node server.jsを実行すると、サーバーがhttp://0.0.0.0:8080で起動します。

注意点

• モノレポ設定でのトレース時、プロジェクトディレクトリがデフォルトでトレースルートとして使用されます。next build packages/web-appの場合、packages/web-appがトレースルートとなり、そのフォルダ外のファイルは含まれません。このフォルダ外のファイルを含めるには、next.config.jsでoutputFileTracingRootを設定します。

module.exports = {
  // これによりモノレポのベースから2ディレクトリ上のファイルが含まれます
  outputFileTracingRoot: path.join(__dirname, '../../'),
}

• Next.jsが必要なファイルを含められなかったり、使用されないファイルを誤って含めてしまう場合があります。そのような場合、next.config.jsでoutputFileTracingExcludesとoutputFileTracingIncludesをそれぞれ活用できます。各設定は、特定のページにマッチするminimatch globsをキーとし、プロジェクトルートからの相対パスのglob配列を値とするオブジェクトを受け入れます。

module.exports = {
  outputFileTracingExcludes: {
    '/api/hello': ['./un-necessary-folder/**/*'],
  },
  outputFileTracingIncludes: {
    '/api/another': ['./necessary-folder/**/*'],
    '/api/login/\\[\\[\\.\\.\\.slug\\]\\]': [
      './node_modules/aws-crt/dist/bin/**/*',
    ],
  },
}

注: outputFileTracingIncludes/outputFileTracingExcludesのキーはglobなので、特殊文字はエスケープする必要があります。

実験的機能 turbotrace

依存関係のトレースは非常に複雑な計算と分析が必要なため遅くなる可能性があります。私たちはJavaScript実装に代わるより高速でスマートな代替手段として、Rustでturbotraceを作成しました。

有効にするには、next.config.jsに次の設定を追加します：

module.exports = {
  experimental: {
    turbotrace: {
      // turbotraceのログレベルを制御、デフォルトは`error`
      logLevel?:
      | 'bug'
      | 'fatal'
      | 'error'
      | 'warning'
      | 'hint'
      | 'note'
      | 'suggestions'
      | 'info',
      // turbotraceのログに分析の詳細を含めるかどうか、デフォルトは`false`
      logDetail?: boolean
      // 制限なしにすべてのログメッセージを表示
      // turbotraceはデフォルトで各カテゴリのログメッセージを1つだけ表示
      logAll?: boolean
      // turbotraceのコンテキストディレクトリを制御
      // コンテキストディレクトリ外のファイルはトレースされない
      // `outputFileTracingRoot`を設定するのと同じ効果
      // `outputFileTracingRoot`とこのオプションの両方が設定されている場合、`experimental.turbotrace.contextDirectory`が使用される
      contextDirectory?: string
      // コード内に`process.cwd()`式がある場合、トレース中に`turbotrace`に`process.cwd()`の値を伝えるためにこのオプションを設定できます
      // 例: require(process.cwd() + '/package.json')はrequire('/path/to/cwd/package.json')としてトレースされる
      processCwd?: string
      // `turbotrace`の最大メモリ使用量を`MB`単位で制御、デフォルトは`6000`
      memoryLimit?: number
    },
  },
}