ESM과 CJS 이중 패키지 출력

ESM(ECMAScript Modules)은 import와 export 구문을 사용하는 공식 JavaScript 모듈 표준입니다. ESM은 정적으로 분석할 수 있으므로 번들러가 빌드 시점에 어떤 내보내기가 실제로 사용되는지 정확히 파악할 수 있고, 그 결과 트리 셰이킹이 가능해집니다. 최신 브라우저와 Node.js는 모두 ESM을 기본적으로 지원합니다.

CJS(CommonJS)는 require()와 module.exports 구문을 사용합니다. CJS는 Node.js의 초기 모듈 시스템이며, 이전 버전의 Node.js 환경, Jest(역사적으로 CJS를 사용함), 그리고 require()를 사용하는 코드와의 호환성을 위해 여전히 필요합니다. CJS는 동적으로 평가되므로 트리 셰이킹이 더 어렵습니다.

최신 npm 패키지는 호환성을 최대화하기 위해 ESM과 CJS를 모두 제공해야 합니다. ESM 소비자(Vite, Next.js, 최신 번들러)는 트리 셰이킹 가능한 가져오기를 사용합니다. CJS 소비자(이전 Node.js 스크립트, 별도 구성 없이 사용하는 Jest)는 require() 호환성을 사용합니다. package.json의 exports 필드는 Node와 번들러에 사용할 형식을 알려 줍니다.

package.json의 exports 필드는 조건에 따라 진입점을 정의하는 최신 방식입니다. 예를 들면 다음과 같습니다: { '.': { 'import': './dist/esm/index.js', 'require': './dist/cjs/index.js', 'types': './dist/esm/index.d.ts' } }. 번들러와 Node.js 12 이상은 exports를 읽어 올바른 형식을 자동으로 선택합니다.

이전 도구는 exports 필드를 이해하지 못합니다. 호환성을 위해 다음도 설정하십시오. main은 CJS 출력(레거시 Node require 대체 경로)을 가리키게 하고, module은 ESM 출력(webpack/rollup을 위한 힌트이며 표준은 아니지만 널리 지원됨)을 가리키게 합니다. 최신 도구는 exports를 우선 사용하고, 레거시 도구는 main/module을 대체 경로로 사용합니다.

"type": "module"을 package.json에 설정하면 패키지의 모든 .js 파일이 ESM으로 취급됩니다. 이중 형식을 제공하려면 명시적인 확장자가 필요합니다. type이 module일 때 ESM 파일에는 .mjs를, CJS 파일에는 .cjs를 사용하거나 그 반대로 설정해야 합니다. tsup가 이 작업을 자동으로 처리합니다.

.mjs(ESM)와 .cjs(CJS) 파일 확장자를 사용하면 type 필드와 관계없이 형식이 명시적으로 지정됩니다. 따라서 모호함을 피할 수 있습니다. 형식을 ['esm', 'cjs']로 설정하고 type 필드를 지정하지 않으면 tsup는 index.js(ESM)와 index.cjs(CJS)를 출력할 수 있으며, 이는 가장 일반적인 규칙과 일치합니다.

패키지가 ESM과 CJS 형식을 모두 제공하면 소비자의 번들러가 같은 프로세스에서 두 버전을 모두 불러올 수 있습니다. 예를 들어 기본 앱에는 ESM 버전을, Jest 테스트에는 CJS 버전을 불러올 수 있습니다. 패키지에 모듈 수준 상태(예: React 컨텍스트)가 있으면 두 인스턴스가 서로 독립적인 상태를 갖게 됩니다. 이것이 이중 패키지 위험입니다.

이 위험을 완화하려면 라이브러리에서 모듈 수준 상태를 제거하고(싱글턴 패턴 사용 금지), exports 조건을 정확하게 사용하여 하나의 형식만 로드되도록 하며, 테스트에서는 번들러가 ESM을 사용하도록 구성해야 한다고 문서화하십시오. 이 위험은 주로 공유 싱글턴을 사용하는 라이브러리에서 문제가 됩니다.

빌드 후 두 형식이 모두 작동하는지 확인하십시오. CJS는 다음과 같이 테스트합니다: node -e "const lib = require('./dist/cjs/index.js'); console.log(lib)". ESM은 다음과 같이 테스트합니다: node --input-type=module --eval "import { Component } from './dist/esm/index.js'; console.log(Component)". 게시하기 전에 두 형식 모두 오류 없이 확인되어야 합니다.

exports 필드는 여러 진입점을 지원합니다: { '.': { import: './dist/esm/index.js', require: './dist/cjs/index.js' }, './utils': { import: './dist/esm/utils.js', require: './dist/cjs/utils.js' } }. 따라서 소비자는 'your-lib' 또는 'your-lib/utils'에서 가져오고 올바른 형식을 사용할 수 있습니다.

라이브러리의 package.json에서 exports 필드의 주된 목적은 무엇인가요?

ESM은 import/export를 사용하며 트리 셰이킹을 가능하게 합니다. CJS는 Node.js 호환성을 위해 require()를 사용합니다. package.json의 exports 필드에서 import/require 조건을 사용하여 두 형식을 모두 제공하십시오. 레거시 대체 경로는 main(CJS)과 module(ESM)입니다. .mjs/.cjs 확장자 또는 type: module을 사용하여 형식을 명시적으로 표시하십시오. 빌드 후 node CLI로 두 형식을 모두 테스트하십시오. 싱글턴 상태를 사용하는 경우 이중 패키지 위험에 주의하십시오.