라이브러리를 위한 Rollup과 tsup 번들링

Vite의 기본 구성은 애플리케이션에 맞게 최적화되어 있어 모든 것을 번들로 묶고, 자산을 처리하며, index.html을 생성합니다. 컴포넌트 라이브러리에는 다른 출력이 필요합니다. 즉, 실행 부담이 없고 React를 번들에 포함하지 않는 순수 ESM/CJS JavaScript 파일과 올바른 TypeScript 선언이 필요합니다. Vite의 라이브러리 모드로도 작업할 수 있지만 Rollup과 tsup이 이 목적에 더 적합하게 설계되어 있습니다.

Rollup은 수년 동안 JavaScript 라이브러리의 표준 번들러였습니다. 뛰어난 트리 셰이킹을 지원하면서 깔끔하고 효율적인 출력을 생성하고, ESM과 CJS 출력 형식을 모두 지원합니다. Rollup의 범위 호이스팅은 모듈 래퍼의 실행 부담을 제거하여 가능한 한 작은 라이브러리 번들을 생성합니다.

tsup은 esbuild를 기반으로 하는 무설정 TypeScript 번들러입니다. esbuild는 밀리초 단위로 컴파일하는 Rollup보다 훨씬 빠르게 마이크로초 단위로 컴파일합니다. 최소 구성인 { entry: ['src/index.ts'], format: ['esm', 'cjs'], dts: true }만으로 두 모듈 형식과 TypeScript 선언을 자동으로 생성합니다.

tsup의 핵심 옵션은 다음과 같습니다. 진입점은 진입점 파일의 배열입니다. 형식은 출력 형식을 지정합니다. ['esm', 'cjs']와 같이 설정합니다. 선언 파일: true는 JS 출력과 함께 .d.ts TypeScript 선언 파일을 생성합니다. 대상은 최소 JavaScript 환경(esnext 또는 es2020)을 설정합니다. 분할: false는 출력을 단일 파일로 유지합니다.

esbuild는 tsup를 통해 Rollup보다 10~100배 빠르게 컴파일합니다. Rollup은 트리 셰이킹을 더 세밀하게 제어하고 청크 경계를 더 폭넓게 조정할 수 있어 출력물을 약간 더 최적화합니다. 대부분의 컴포넌트 라이브러리에서는 개발 시 tsup의 속도가 더 큰 이점입니다. 트리 셰이킹을 최대한 제어하거나 복잡한 다중 진입점 구성을 사용하는 경우에는 Rollup을 선호합니다.

React 라이브러리에서 가장 중요한 번들러 구성은 React 또는 ReactDOM을 절대 번들에 포함하지 않는 것입니다. React와 ReactDOM을 외부로 지정하여 출력물에서 제외하십시오. 라이브러리가 React를 번들에 포함하면 소비자는 번들에 포함된 React와 앱에서 사용하는 React, 이렇게 두 개의 React 사본을 사용하게 됩니다. React 인스턴스가 여러 개 존재하면 모든 React 훅이 작동하지 않습니다.

tsup 구성에서는 external 옵션을 사용합니다: external: ['react', 'react-dom']. Rollup 구성에서는 external: ['react', 'react-dom', 'react/jsx-runtime']로 설정합니다. 라이브러리가 JSX Transform을 사용하는 경우 react/jsx-runtime도 포함하십시오. 라이브러리가 선언한 다른 피어 종속성도 외부로 지정하십시오.

TypeScript 라이브러리를 위한 최소한의 Rollup 구성에는 세 가지 플러그인이 필요합니다. @rollup/plugin-typescript는 TypeScript 컴파일에, @rollup/plugin-node-resolve는 node_modules 가져오기의 경로 해석에, @rollup/plugin-commonjs는 CommonJS 종속성을 번들용 ESM으로 변환하는 데 사용합니다. 선언 파일을 생성하려면 rollup-plugin-dts를 추가하십시오.

일반적인 이중 형식 라이브러리 출력은 다음과 같습니다. ESM 소비자용으로는 dist/esm/index.js와 dist/esm/index.d.ts를, CJS 소비자용으로는 dist/cjs/index.js와 dist/cjs/index.cjs를 사용합니다. package.json의 exports 필드는 이러한 경로를 올바른 환경에 매핑합니다. TypeScript 선언 파일은 해당 JS 파일과 같은 위치에 저장됩니다.

대규모 라이브러리는 여러 진입점을 제공하면 소비자가 필요한 항목만 가져올 수 있어 유리합니다. 예를 들면 다음과 같습니다: entry: ['src/index.ts', 'src/utils.ts', 'src/hooks.ts']. 각 진입점에는 자체 출력 파일이 생성됩니다. package.json의 exports 필드는 각 공개 경로를 해당 출력에 매핑합니다: './utils' → './dist/utils.js'.

package.json의 scripts에 빌드 명령을 추가하십시오: "build": "tsup". tsup는 루트에 있는 tsup.config.ts에서 구성을 읽습니다. prepublish 스크립트는 빌드를 실행해야 합니다. "prepublishOnly": "npm run build"를 설정하면 npm에 배포하기 전에 패키지가 항상 빌드됩니다.

React 컴포넌트 라이브러리를 번들로 만들 때 React를 외부로 지정해야 하는 이유는 무엇인가요?

tsup(esbuild 기반)은 format: ['esm', 'cjs']와 dts: true를 사용하여 빠르고 별도 구성 없이 번들링할 수 있게 해 줍니다. Rollup은 @rollup/plugin-typescript를 사용하여 트리 셰이킹을 더 세밀하게 제어할 수 있습니다. 가장 중요한 규칙은 react, react-dom 및 모든 피어 종속성을 항상 외부로 지정하여 번들에 포함되지 않게 하는 것입니다. TypeScript 선언 파일을 함께 생성하면서 dist/esm/ 및 dist/cjs/에 출력하십시오. 여러 진입점을 사용하면 소비자 측에서 트리 셰이킹을 세밀하게 수행할 수 있습니다.