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は自動的にstandaloneフォルダを作成し、本番デプロイに必要なファイル（node_modules内の選択されたファイルを含む）のみをコピーできます。

この自動コピー機能を活用するには、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ファイルが自動的にそれらを提供します。

知っておくと良いこと:

• プロジェクトが特定のポートやホスト名をリッスンする必要がある場合、server.jsを実行する前にPORTまたはHOSTNAME環境変数を定義できます。例えば、PORT=8080 HOSTNAME=0.0.0.0 node server.jsを実行すると、http://0.0.0.0:8080でサーバーが起動します。
• プロジェクトがデフォルトのloaderで画像最適化を使用している場合、依存関係としてsharpをインストールする必要があります：

npm i sharp

yarn add sharp

pnpm add sharp

bun add sharp

注意点

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

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

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

module.exports = {
  experimental: {
    outputFileTracingExcludes: {
      '/api/hello': ['./un-necessary-folder/**/*'],
    },
    outputFileTracingIncludes: {
      '/api/another': ['./necessary-folder/**/*'],
    },
  },
}

• 現在、Next.jsは出力された.nft.jsonファイルを何も処理しません。これらのファイルはVercelなどのデプロイプラットフォームによって読み込まれ、最小限のデプロイメントを作成する必要があります。将来のリリースでは、これらの.nft.jsonファイルを活用する新しいコマンドが計画されています。

実験的な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のコンテキストディレクトリを制御
      // コンテキストディレクトリ外のファイルはトレースされません
      // `experimental.outputFileTracingRoot`を設定するのと同じ効果があります
      // `experimental.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
    },
  },
}