next.js - Output File Tracing

next.js는 빌드 시 자동으로 모든 페이지와 그 의존성을 트랙킹하여 배포시 필요한 파일을 알아낸다. 이렇게 함으로써 배포될 파일의 크기를 줄일 수 있다.

이전에 도커로 배포할 땐, 모든 의존성을 가져온 후 next start를 실행해야했다. 하지만 next.js 12부터는 Output File Tracing을 통해 .next/ 디렉터리만 있으면 된다. 단, standalone 모드를 켜야한다.

동작방식

next build가 실행되는 동안, next.js는 @vercel/nft를 사용하여 정적으로 import, require, fs를 분석하여 로드될 페이지를 알아낸다.

next.js의 프로덕션 서버 또한 필요한 파일과, .next/next-server.js.nft.json 을 트래킹한다. .nft.json를 활용할 때는 nft.json에 상대적인 모든 trace의 파일리시트를 읽고, 배포할 위치에 복사한다.

standalone mode

next.js는 node_modules에서 필요한 파일을 뽑아내 배포시에 필요한 파일만으로 구성된 standalone 폴더를 구성할수 있다. 이를 활성화하기 위해선 next.config.js에서 다음과 같이 설정해야한다.

1
2
3

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

이렇게 하면, 빌드시 .next/standalone 폴더가 생성되고, 여기에 node_modules에서 필요한 파일만 저장된다.

또한 최소화된 server.js가 next start 대신에 사용된다. 이 최소화된 서버는 public, .next/static 폴더를 디폴트로 복사하지 않는다. CDN에 저장되는 것이 가장 이상적이기 때문이다. 다만, standalone/.next/static 폴더에 수동으로 복사할 수는 있다.

Note : next.config.js는 next build 시 읽혀져 server.js에 복사된다. 만약 serverRuntimeConfig 또는 publicRuntimeConfig옵션 이 사용된다면, 빌드시 다른 값으로 변경된다.

만약 프로젝트에서 디폴트 로더로 Image Optimization를 사용중이라면, sharp를 설치해야한다.

1

npm i sharp

주의사항

• 모노레포 설정에서 tracing 하면, 프로젝트의 디렉터리가 기본으로 사용된다. next build packages/web-app에서 packages/web-app이 tracing root가 되고, 해당 폴더 밖에 있는 파일들은 포함되지 않는다. 만약 바깥 파일도 tracing에 포함하고 싶으면, experimental.outputFileTracingRoot를 설정할 수 있다.

  1 2 3 4 5 6 7

  // packages/web-app/next.config.js module.exports = { experimental: { // this includes files from the monorepo base two directories up outputFileTracingRoot: path.join(__dirname, '../../'), }, }

• 필요한 파일을 가져오는데 실패하거나 잘못된 파일을 가져오는 경우가 있다. 이러한 경우 unstable_includeFiles, unstable_excludeFiles 같은 page config를 export 하면 된다. 각 prop은 minimatch의 배열을 받는다. 프로젝트 루트를 루트로 삼고 설정하면 된다

• 현재 Next.js는 .nft.json을 가지고 아무것도 하지 않는다. 이 파일은 어플리케이션이 배포되는 시스템에서 minimal deployment를 위해 사용된다. 향후 .nft.json 를 활용한 커맨드를 낼 계획이 있다.

Experimental turbotrace

의존성을 tracing하는 것은 느려질 수 있다. 따라서 next.js 팀은 turbotrace를 러스트로 작성하여 이 과정을 빠르게 만들었다.

활성화를 위해선 next.config.js에서 다음과 같이 설정할 수 있다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

// next.config.js
module.exports = {
  experimental: {
    turbotrace: {
      // control the log level of the turbotrace, default is `error`
      logLevel?:
      | 'bug'
      | 'fatal'
      | 'error'
      | 'warning'
      | 'hint'
      | 'note'
      | 'suggestions'
      | 'info',
      // control if the log of turbotrace should contain the details of the analysis, default is `false`
      logDetail?: boolean
      // show all log messages without limit
      // turbotrace only show 1 log message for each categories by default
      logAll?: boolean
      // control the context directory of the turbotrace
      // files outside of the context directory will not be traced
      // set the `experimental.outputFileTracingRoot` has the same effect
      // if the `experimental.outputFileTracingRoot` and this option are both set, the `experimental.turbotrace.contextDirectory` will be used
      contextDirectory?: string
      // if there is `process.cwd()` expression in your code, you can set this option to tell `turbotrace` the value of `process.cwd()` while tracing.
      // for example the require(process.cwd() + '/package.json') will be traced as require('/path/to/cwd/package.json')
      processCwd?: string
      // control the maximum memory usage of the `turbotrace`, in `MB`, default is `6000`.
      memoryLimit?: number
    },
  },
}

출처

https://nextjs.org/docs/advanced-features/output-file-tracing