Edge Runtime#

• 상위 메뉴: API Reference
• 전체 목차: Next.js 학습 문서

학습 목표#

• Node.js Runtime과 Edge Runtime 두 서버 런타임의 차이를 이해한다.
• Edge Runtime의 제약(ISR 미지원, 일부 Node.js API 미지원)을 파악한다.
• Edge Runtime이 지원하는 API 범주와 지원하지 않는 언어 기능을 확인한다.
• unstable_allowDynamic으로 동적 코드 평가 검사를 완화하는 방법을 이해한다.

핵심 개념 및 설명#

Next.js에는 애플리케이션에서 사용할 수 있는 두 가지 서버 런타임이 있다.

• Node.js Runtime(기본값): 모든 Node.js API에 접근할 수 있으며, 애플리케이션을 렌더링하는 데 사용된다.
• Edge Runtime: 더 제한된 API 집합만 포함하며, Proxy에서 사용된다.

주의사항#

알아두면 좋은 점:

- Edge Runtime은 모든 Node.js API를 지원하지 않는다. 일부 패키지는 예상대로 동작하지 않을 수 있다.

- Edge Runtime은 증분 정적 재생성(Incremental Static Regeneration, ISR)을 지원하지 않는다.

- 두 런타임 모두 배포 어댑터에 따라 스트리밍을 지원할 수 있다.

Reference#

<a id="reference"></a>

Edge Runtime은 다음 API를 지원한다.

Network APIs#

Encoding APIs#

Stream APIs#

Crypto APIs#

Web Standard APIs#

Next.js Specific Polyfills#

• `AsyncLocalStorage`

Environment Variables#

next dev와 next build 양쪽 모두에서 process.env로 환경 변수에 접근할 수 있다.

Unsupported APIs#

Edge Runtime에는 다음과 같은 제약이 있다.

• 네이티브 Node.js API는 지원하지 않는다. 예를 들어 파일 시스템을 읽거나 쓸 수 없다.
• node_modules는 ES Modules로 구현되어 있고 네이티브 Node.js API를 사용하지 않는 한 사용할 수 있다.
• require를 직접 호출하는 것은 허용되지 않는다. 대신 ES Modules를 사용해야 한다.

다음 JavaScript 언어 기능은 비활성화되어 있으며 동작하지 않는다.

드문 경우지만, 코드(또는 그 코드가 import하는 모듈)에 런타임에는 도달할 수 없지만 트리쉐이킹으로 제거되지 않는 동적 코드 평가 구문이 포함될 수 있다. 이럴 때는 Proxy 설정에서 특정 파일에 대한 검사를 완화할 수 있다.

export const config = {
  unstable_allowDynamic: [
    // 단일 파일을 허용한다
    '/lib/utilities.js',
    // glob으로 function-bind 서드파티 모듈 안의 모든 파일을 허용한다
    '**/node_modules/function-bind/**',
  ],
}

unstable_allowDynamic은 특정 파일에 대해 동적 코드 평가 검사를 무시하는 glob 또는 glob 배열이다. 이 glob은 애플리케이션 루트 폴더를 기준으로 한 상대 경로다.

이 구문이 Edge에서 실제로 실행되면 오류가 발생하며 런타임 에러를 일으킨다는 점에 유의한다.

예제 및 데모 설계#

• Phase 1에서는 구현 예정이다. Phase 2에서 Proxy 데모를 만들 때, runtime = 'edge'로 설정한 경로에서 파일 시스템 API를 호출해 Edge Runtime 제약이 실제로 오류를 발생시키는지 확인하는 데모를 설계한다.
• unstable_allowDynamic 설정 전후로 빌드 경고·에러가 어떻게 달라지는지 비교하는 시나리오를 포함한다.

연습 문제#

1. Edge Runtime이 지원하지 않는 것은?

• A. fetch, Request, Response 같은 네트워크 API
• B. 증분 정적 재생성(ISR)
• C. crypto, SubtleCrypto 같은 암호화 API

1. Edge Runtime에서 eval이나 new Function(evalString)을 코드가 실제로 실행할 때 일어나는 일은?

• A. 자동으로 Node.js Runtime으로 전환된다.
• B. 무시되고 빈 값을 반환한다.
• C. 지원되지 않는 기능이므로 런타임 에러가 발생한다.

챕터 요약#

• Next.js는 기본값인 Node.js Runtime과, 더 제한된 API를 제공하는 Edge Runtime 두 가지를 제공한다.
• Edge Runtime은 Proxy에서 사용되며, 일부 Node.js API와 ISR을 지원하지 않는다.
• Edge Runtime은 Network·Encoding·Stream·Crypto·Web Standard APIs와 AsyncLocalStorage 폴리필, process.env 환경 변수 접근을 지원한다.
• require 직접 호출과 eval, new Function, WebAssembly.compile/instantiate는 Edge Runtime에서 동작하지 않는다.
• unstable_allowDynamic으로 도달 불가능한 동적 코드 평가 구문에 대한 검사를 파일 단위로 완화할 수 있다.