Npm 패키지 만들기

May 5, 2023 5 분 소요

TypeScript기반 NPM 패키지 만들기

개인적으로 사용할 패키지를 만들어서 npm에 배포해보았다.

NPM에 개인 저장소를 만드는 건 돈을 내므로 공개 패키지로 올렸다. 사실 비밀 패키지를 NPM에 올릴 이유는 전혀 없다. Git을 지원하는 아무 저장소에 올리면 되기 때문이다. NPM 명령어를 사용할 수 있다는 편리함은 있지만 사실 공개 패키지도 아닌 비밀 패키지를 올려봤자 남들은 사용할 수 없으니 문제만 더 생길 뿐이다. 이 경우 package.json에 file:... 형식으로 적으면 되는데 이건 밑에서 다시 설명하겠다.

이 포스트에서는 commonjs와 esm을 동시에 지원하는 TypeScript 기반 패키지를 만드는 법에 대해 중점적으로 설명하겠다.

commonjs와 esm

commonjs와 esm은 자바스크립트 모듈 시스템이다. commonjs는 node.js에서 사용하는 모듈 시스템이고, esm은 브라우저에서 사용하는 모듈 시스템이다. 둘은 호환되지 않는다. 브라우저에서는 commonjs를 사용할 수 없고, node.js에서는 esm을 사용할 수 없다. 그런데 nodejs 프로젝트를 typescript 기반으로 만들 경우 이번에는 또 node.js에서 esm을 사용한다. 여기서 문제가 발생한다. 처음에는 이 문제를 해결하기 위해 package.json에 type 속성을 추가해 보았다.

{
  "type": "module"
}

그런데 TypeScript 컴파일러를 사용하는 패키지를 모듈로 설정할 경우 nodejs에서 사용할 때 문제가 생긴다. nodejs에서는 import를 할 때 파일명 뒤에 .js를 붙여야만 모듈을 인식하는데 타입스크립트로 빌드한 경우 이게 누락된다. 그렇다고 후처리 과정에서 강제로 .js를 붙이게 만들면 이번에는 브라우저에서 모듈을 로드할 때 문제가 생긴다. 따라서 라이브러리 패키지를 만들 때는 모듈 패키지로 만들어서는 안 된다.

다양한 삽질이 있었지만 그 과정을 다 적지는 않겠다. 아래부터는 거두절미하고 패키지를 만드는 방법을 설명하겠다.

TypeScript 패키지 만들기

공통 옵션으로 할 tsconfig.json을 만든다. 나는 이렇게 만들었다.

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    },
    "allowJs": true,
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "declaration": true,
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "strictBindCallApply": true,
    "strictPropertyInitialization": true,
    "noImplicitThis": true,
    "alwaysStrict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "skipLibCheck": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "src/tests", ".vscode"]
}

다음, commonjs(nodejs)와 esm(브라우저, 타입스크립트 기반 node) 에서 사용할 tsconfig를 각각 만든다.

tsconfig.browser.json

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "module": "ESNext",
    "outDir": "./build/browser"
  }
}

tsconfig.node.json

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "module": "CommonJS",
    "outDir": "./build/node"
  }
}

그리고 package.json을 아래와 같이 만든다.

package.json

{
  "name": "@webstory/toolbox",
  "version": "1.0.9",
  "description": "JavaScript utility classes toolbox",
  "scripts": {
    "build:node": "tsc --project tsconfig.node.json",
    "build:browser": "tsc --project tsconfig.browser.json",
    "build": "npm run build:node && npm run build:browser",
    "test": "jest",
    "clean": "rimraf build/*"
  },
  "exports": {
    ".": {
      "import": {
        "types": "./build/browser/index.d.ts",
        "default": "./build/browser/index.js"
      },
      "require": {
        "types": "./build/node/index.d.ts",
        "default": "./build/node/index.js"
      }
    }
  },
  "main": "./build/browser/index.js",
  "repository": {
    "type": "git",
    "url": "https://github.com/webstory/toolbox"
  },
  "keywords": ["utility", "util", "utils", "toolbox"],
  "author": "Hoya Kim <hoya@mychar.info>",
  "license": "MIT",
  "devDependencies": {
    "@babel/core": "^7.21.8",
    "@babel/preset-env": "^7.21.5",
    "@babel/preset-typescript": "^7.21.5",
    "@types/jest": "^29.5.1",
    "babel-jest": "^29.5.0",
    "jest": "^29.5.0",
    "prettier": "^2.8.8",
    "rimraf": "^5.0.0",
    "ts-jest": "^29.1.0",
    "typescript": "^5.0.4"
  }
}

더 자세한 안내는 https://www.typescriptlang.org/docs/handbook/esm-node.html 에서 확인할 수 있다.

패키지 설정에서 주의할 점은 "type": "module"을 넣지 않는 것이다.

exports 설정에 따라 commonjs와 esm 각각의 패키지를 빌드한다. “main”은 일종의 fallback으로 사용된다.

아래 테스트 환경 설정과 추가 환경 설정은 패키지 빌드와는 관계가 없으며 다만 npm에 공개할 패키지를 만들 때 예의상? 필요하다고 생각하여 추가하였다.

테스트 환경 설정

추가로 jest.config.js 파일은 아래와 같이 생겼다.

module.exports = {
  preset: "ts-jest/presets/js-with-ts-esm",
  testEnvironment: "node",
  testMatch: ["<rootDir>/src/tests/**/*.test.[jt]s"],
};

여기서 module.exports 가 아니라 export default 를 사용하면 jest로더가 에러를 발생시킨다. 따라서 module.exports 를 사용해야 한다.

또한 Jest는 babel을 사용해 타입스크립트를 빌드하기 때문에 babel 관련 패키지도 설치하였고 babel.config.js 파일도 만들었다.

module.exports = {
  presets: [
    ["@babel/preset-env", { targets: { node: "current" } }],
    "@babel/preset-typescript",
  ],
};

즉 위의 package.json에서

  "devDependencies": {
    "@babel/core": "^7.21.8",
    "@babel/preset-env": "^7.21.5",
    "@babel/preset-typescript": "^7.21.5",
    "@types/jest": "^29.5.1",
    "babel-jest": "^29.5.0",
    "jest": "^29.5.0",
    "ts-jest": "^29.1.0",
  }

는 오직 Jest를 위한 패키지이다. 테스트를 안 할 작정이라면 👀 이 패키지들은 필요 없다.

추가 환경 설정

prettier는 아래와 같이 설정했다. 패키지 빌드에 필요하지는 않으나 코드 스타일을 통일하기 위해 사용하였다.

.prettierrc

{
  "tabWidth": 2,
  "useTabs": false,
  "singleQuote": true,
  "trailingComma": "es5",
  "printWidth": 160,
  "pluginSearchDirs": [
    "."
  ]
}

테스트 및 빌드

npm run test
npm run build

패키지 디버깅

NPM에 매번 올려서 테스트하는 건 번거롭기 때문에 빌드된 패키지를 파일 시스템 상에서 직접 참고하는 방법이 필요하다.

프로젝트 폴더 바깥, 하지만 같은 부모 디렉토리인 곳에서 새 프로젝트를 만들고 아래와 같이 사용할 수 있다.

package.json

  "dependencies": {
    "@webstory/toolbox": "file:../toolbox"
  },

참고로 nodejs에서 typescript 기반으로 개발한 패키지를 디버깅할 때는 ts-node 패키지를 사용하면 된다. 이때 nodemon과 함께 사용하는 스크립트는 아래와 같다.

 "scripts": {
    "build": "tsc",
    "dev": "nodemon --watch \"src/**\" --exec npx ts-node --esm src/index.ts",
    "test": "echo \"Error: no test specified\" && exit 1"
  },

toolbox 패키지를 직접 참고하기 때문에 만약 toolbox에서 npm run clean을 실행할 경우 위 패키지들에서 로드 에러가 발생할 것이다. 그걸로 내가 올바를 버전의 패키지를 디버깅하고 있다는 확신을 얻을 수 있다.

이 패키지는 자바스크립트 기반 nodejs 프로젝트 즉 commonjs 기반에서 사용할 경우에도 문제가 생기지 않음을 확인했다.

Github CI 사용

Github Actions를 사용하여 CI를 구축하였다.

프로젝트 루트에 .github/workflows/ci.yaml 파일을 만들고 아래와 같이 작성한다.

name: CI

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    env:
      NPM_TOKEN: $\{\{ secrets.NPM_TOKEN \}\}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 16
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Build
        run: npm run build

      - name: Publish to npm
        run: npm publish --access public
        if: github.ref == 'refs/heads/main'

위 yaml 파일은 아래와 같은 작업을 수행한다.

main 브랜치에 push가 발생하면
노드 16을 설치하고
npm ci를 실행하여 패키지를 설치하고
npm test를 실행하여 테스트를 수행하고
npm run build를 실행하여 패키지를 빌드하고
npm publish를 실행하여 패키지를 npm에 배포한다.

이때 npm publish를 실행하기 위해 NPM_TOKEN을 사용한다. 이 토큰은 npmjs.com에서 발급받을 수 있다. 권장 사항은 granular access token을 발급하라고 하는데 이것은 365일까지만 사용할 수 있기 때문에 GitHub용으로는 classic token을 발급받는 걸 더 권장한다. Token expire로 배포가 안 되는 게 토큰이 유출되는 것보다 더 문제일 것이다.

Github에서 배포를 수행하기 때문에 로컬 npm publish 관련 스크립트는 존재하긴 하지만 블로그에서는 삭제하였다. 두 군데에서 배포를 수행할 경우 버전 충돌이 발생할 수 있어서 추천하지 않는다. 어차피 main 브랜치가 아니면 배포가 수행되지 않으니 로컬에서는 배포하지 않는 것이 좋다.

Twitter Facebook LinkedIn

Hoya Kim

Npm 패키지 만들기

TypeScript기반 NPM 패키지 만들기

commonjs와 esm

TypeScript 패키지 만들기

테스트 환경 설정

추가 환경 설정

테스트 및 빌드

패키지 디버깅

Github CI 사용

공유하기

댓글남기기

참고

Lazy load image

Expanding wsl vdisk

Exact size placeholder

Pen pressure canvas