npm 라이브러리 배포 (with Typescript)

지난 게시글에 npm으로 라이브러리를 배포했으나, 해당 라이브러리를 TS 환경의 프로젝트에서 사용하려고 하면 타입 에러가 발생했다.

이는 라이브러리의 타입 정의가 없어서인데, 즉 쉽게 말해 dist 폴더에 index.d.ts 파일이 없기 때문에 발생한 것이다.

 

그렇다면 라이브러리에 적합한 타입 정의를 주어(= index.d.ts 파일을 생성하여) TS 환경의 프로젝트에서도 사용가능하게 만들어야 한다.

 

우선 그렇다면 dist 폴더는 무엇이고 어떤 역할을 할까?

 

 

dist

distribution(유통, 배포)의 약자

실제 운영 환경에서 사용되는 축소/연결 버전

ts 환경의 프로젝트를 빌드하면 js 코드로 컴파일된 결과물이 dist 폴더에 담긴다.

 

배포된 라이브러리를 install 하여 사용할 때는 해당 라이브러리의 dist 폴더를 사용하는 것이므로 그 외의 폴더나 코드는 라이브러리의 용량만 커지게 할 뿐 필요가 없다.

그래서 .npmignore에 라이브러리에는 올리지 않을 폴더 및 파일을 작성한다.

// .npmignore

node_modules/
src/
public/
tsconfig.json

 

 

TS에서 사용

최근에는 TS 환경의 프로젝트가 굉장히 많아지고 있기 때문에 라이브러리도 type을 제공해야 할 필요가 있다.

(TS 환경에서는 type이 없으면 라이브러리 import 시 오류가 발생한다.)

 

이를 위해서는 dist 폴더 내부에 export할 컴포넌트의 타입이 작성된 index.d.ts 파일이 생성되어야 한다.

즉, 빌드 시 src/index.ts를 컴파일한 결과인 index.js와 index.d.ts 파일이 생성되어야 한다는 뜻이다.

 

자동 생성 + 위치 지정

// tsconfig.json

{
  "compilerOptions": {
	  ...
    "declaration": true,
    "outDir": "./dist"
  },
}

 

 

빌드 시 포함할/제외할 파일 및 폴더 지정

// tsconfig.json

"include": ["./src/**/*.tsx", "./src/**/*.ts"],
"exclude": ["node_modules", "dist", "src/**/*.stories.tsx"],

※ stories 파일은 프로젝트에서 사용할 때 필요 없기 때문에 제외함

 

 

💥 나는 그럼에도 index.d.ts 파일이 생성되지 않고 다른 생뚱맞은 파일들이 생성됐기 때문에 외부 라이브러리의 힘을 빌렸다. → vite-plugin-dts

npm i -D vite-plugin-dts

 

 

vite.config.ts 파일의 plugins에 dts 추가

dts({
  insertTypesEntry: true,
}),

💡 dts : 타입스크립트 정의 파일을 생성하는 플러그인

insertTypesEntry : 타입 정의 파일의 엔트리 포인트를 자동으로 삽입하는 속성

 

⬇

// vite.config.ts

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import dts from "vite-plugin-dts";
import path from "path";

// <https://vitejs.dev/config/>
export default defineConfig({
  plugins: [
    react(),
    dts({
      insertTypesEntry: true,
    }),
  ],
  build: {
    lib: {
      entry: path.resolve(__dirname, "src/index.ts"),
      name: "라이브러리 이름",
      formats: ["es", "cjs"],
      fileName: (format) => `index.${format}.js`,
    },
    rollupOptions: {
      external: ["react", "react-dom", "styled-components"],
      output: {
        globals: {
          react: "React",
          "react-dom": "ReactDOM",
        },
      },
    },
  },
});

lib (라이브러리 모드 설정)

• entry : 어떤 파일을 기준으로 라이브러리를 번들링 할 것인지
• name : 라이브러리 전역 변수 이름
• formats : 라이브러리 빌드 형식
  • es : ES Module (import/export)
  • cjs : CommonJS (require)
• fileName : 각 형식에 대해 생성될 파일 이름 정의
  • es → index.ex.js
  • cjs → index.cjs.js

 

rollupOptions (Rollup 번들러 설정 정의)

※ Rollup : vite가 내부적으로 사용하는 번들러

• external : 번들에 포함하지 않을 라이브러리 (해당 라이브러리를 사용하는 외부 프로젝트에서 external에 정의된 종속성은 따로 설치해야 함)
• output : 번들 결과 설정
  • globals: 라이브러리 외부에 존재하는 dependency를 위해 번들링 시 사용될 전역 변수

빌드 결과

 

 

Package.json 수정

// package.json
  
"types": "./dist/index.d.ts",
"main": "./dist/index.cjs.js",
"module": "./dist/index.es.js",

• types : TS 타입 정의 파일 경로 지정
• main : CommonJS 형식의 엔트리 포인트 지정
• module: ESModule 형식의 엔트리 포인트 지정

또는

// package.json

"exports": {
  ".": {
    "types": "./dist/index.d.ts",
    "import": "./dist/index.es.js",
    "require": "./dist/index.cjs.js"
  }

• exports : 모듈 해석을 보다 정밀하게 설정 (더 구체적이고 현대적인 방법)
  • types → TS
  • import → ESModule
  • require → CommonJS

 

 

 

명령어

빌드

npm run build

 

버전 패치

 npm version patch

 

버전 배포

npm publish

 

 

 

 

---

[ 참고 자료 ]

coyo-hm.github.io

내가 만든 npm 패키지가 import가 안되는 이슈 (feat. tsconfig.json & pacakge.json)