[TypeScript] npm 라이브러리 배포하기

TypeScript로 만든 모듈을 npm에 배포까지 해보자

절차

1. 프로젝트 생성 및 세팅

2. ts 모듈 개발

3. ts 모듈 컴파일 - CommonJS, ES Modules 다중 지원

4. package.json 수정

5. 배포

---

사전 지식

모듈 방식

모듈 방식에는 Commonjs, ES Modules 방식이 존재한다.

 

CommonJS

const example = require('./example')
const {example} = require('./exmaple')

module.exports = {example}
module.exports = {default: example}

ES Modules

import example from './example'
import {example} from './example'

export {example}
export default example

위 처럼 불러오기, 내보내기 방식이 다르고 두 방식 모두 활발하게 사용 중 이라 두 모듈을 복수 지원해주는게 좋다.

---

프로젝트 생성 및 세팅

npm 사이트에 검색하여 중복 되지 않는 이름을 찾아 개발할 라이브러리 이름을 정하고 

https://www.npmjs.com/

npm

npm init으로 초기 세팅을 한다.

mkdir ${project-name}
cd ${project-name}
npm init

초기 세팅 이후 package.json에 한 문장을 추가한다.

{
  ...,
  "type": "module",
}

프로젝트 내에서 ES modules 방식을 사용하기 위해 추가하였다.

 

typescript를 활용하기 위해 설치한다.

npm i -D typescript

---

ts 모듈 개발

src폴더를 만들고 그 안에 index.ts 모듈을 작성한다.

export const hello = (name: string): string => {
  return `hello ${name}`;
};

---

ts 모듈 컴파일

우리는 ts 파일을 컴파일 하여 dist 디렉토리에 저장하도록 할 것 이다.

 

그러기 위한 세팅 방법을 설명하겠다.

 

tsc로 ts 파일을 js를 변환을 할건데 이 때, 두번의 컴파일을 할 것 이다.

 

CommonJS 모듈에 맞게끔 한번, ES Modules에 맞게끔 한번.

 

프로젝트 루트에 3개의 tsconfig 파일을 만든다.

├── tsconfig-base.json
├── tsconfig-cjs.json
└── tsconfig.json

base는 tsconfig-cjs와 tsconfig에서 상속받아 사용할 공통 설정들을 담는다.

 

tsconfig-cjs는 CommonJS를 위한 파일이고, 일반 tsconfig는 ES Modules를 위한 파일이다.

(위 package.json 에서 기본 모듈 타입을 ES Modules로 지정했기 때문에 default config를 ES Modules에 맞게 작성하겠다)

 

tsconfig-base.json

{
  "compilerOptions": {
    "target": "ES5",
    "allowJs": true,
    "allowSyntheticDefaultImports": true,
    "baseUrl": "src",
    "declaration": true,
    "esModuleInterop": true,
    "inlineSourceMap": false,
    "listEmittedFiles": false,
    "listFiles": false,
    "moduleResolution": "node",
    "noFallthroughCasesInSwitch": true,
    "pretty": true,
    "resolveJsonModule": true,
    "rootDir": "src",
    "skipLibCheck": true,
    "strict": true,
    "traceResolution": false
  },
  "compileOnSave": false,
  "exclude": ["node_modules", "dist"],
  "include": ["src"]
}

남은 두 파일은 compiler option을 다르게 작성한다.

 

tsconfig-cjs.json

{
  "extends": "./tsconfig-base.json",
  "compilerOptions": {
    "module": "commonjs",
    "outDir": "dist/cjs",
    "target": "es2015"
  }
}

tsconfig.json

{
  "extends": "./tsconfig-base.json",
  "compilerOptions": {
    "module": "esnext",
    "outDir": "dist/mjs",
    "target": "esnext"
  }
}

위 파일들을 작성 후 프로젝트 루트에  fixup.sh이라는 스크립트 파일을 만든다.

 

fixup.sh

cp dist/mjs/index.d.ts dist 

rm -rf dist/*/index.d.ts 

cat >dist/cjs/package.json <<!EOF
{
    "type": "commonjs"
}
!EOF

cat >dist/mjs/package.json <<!EOF
{
    "type": "module"
}
!EOF

 

index.d.ts 파일을 dist 아래 경로로 옮기고 (중복 제거) 빌드된 파일들이 저장될 디렉토리에 package.json을 생성하는 스크립트이다.

---

package.json 수정

빌드 커멘드를 추가하고, export 관련한 설정을 추가하겠다.

 

package.json

{
  "scripts": {
    "build": "rm -fr dist/* && tsc -p tsconfig.json && tsc -p tsconfig-cjs.json && ./fixup.sh"
  },
}

build 스크립트를 위와 같이 추가해준다.

 

dist 디렉토리를 지우고, tsconfig 파일을 이용하여 각 모듈에 맞게끔 컴파일 두번 한다.

 

fixup 스크립트로 dist/mjs/index.d.ts 파일을 dist/index.d.ts로 복사하고 각 디렉토리의 index.d.ts 파일을 삭제한다.

 

그 다음, dist 하위 각 디렉토리에 맞게끔 package.json을 추가한다.

 

여기 까지 완료했으면 마무리 export 관련 설정만 추가하면 배포 준비가 끝난다.

 

package.json

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

이 항목들을 추가해주면 각 모듈 환경에 맞게끔 불러오기가 가능하다.

 

---

npm에 배포

먼저 npm에 올릴 필요가 없는 파일들을 ignore 해주겠다.

 

.npmignore

**/*
!/dist/**

 

나의 경우는 전부 ignore 하고 컴파일된 파일만 unignore 하였다.

 

npm 홈페이지에서 가입을 한다.

https://www.npmjs.com/

npm

터미널에서 npm login을 하고

npm login

npm publish만 입력하면 배포가 된다.

npm publish

---

Ref.

https://www.sensedeep.com/blog/posts/2021/how-to-create-single-source-npm-module.html