빈 디렉터리에서 시작해 프로덕션 NPM 패키지를 설정하는 방법

https://www.totaltypescript.com/how-to-create-an-npm-package#39-set-up-a-ci-script

해당 글을 바탕으로 NPM 패키지 설정 과정을 간단히 요약해 보았습니다. 

https://github.com/mattpocock/tt-package-demo

1. Git 설정

패키지를 버전 관리하기 위해 Git을 사용합니다.

Git 초기화

git init

.gitignore 파일 생성

node_modules

커밋 + 리포지토리 생성 + 푸시

gh repo create tt-package-demo --source=. --public
git push --set-upstream origin main

2. package.json 설정

package.json 파일은 패키지의 메타데이터를 정의하는 파일로, 패키지 이름, 버전, 라이선스, README 등의 정보를 포함됩니다.

{
  "name": "tt-package-demo",
  "version": "1.0.0",
  "description": "A demo package for Total TypeScript",
  "keywords": ["demo", "typescript"],
  "license": "MIT",
  "author": "Matt Pocock <team@totaltypescript.com>",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/mattpocock/tt-package-demo.git"
  },
  "files": ["dist"],
  "type": "module"
}

• name: 패키지의 고유한 이름입니다. NPM 레지스트리에서 유일해야 하며, 조직 범위로 패키지를 생성하려면 @your-org/package-name과 같은 형태를 사용할 수 있습니다.
• version: 패키지의 버전입니다. SemVer 규칙에 따라 관리하며, 배포할 때마다 적절히 증가시켜야 합니다.
• files: NPM에 배포할 때 포함될 파일 목록입니다. 여기서는 빌드된 코드가 포함될 dist 폴더만 지정했습니다.
• type: ECMAScript 모듈을 사용하려면 "module"로 설정합니다.

라이선스 설정

{
  "license": "MIT"
}

MIT License

Copyright (c) [year] [fullname]

Permission is hereby granted, free of charge, to any person obtaining a copy
...

NPM 패키지 레지스트리에서 패키지의 설명을 보여주는 README.md 파일도 포함해야 합니다.

# tt-package-demo

A demo package for Total TypeScript.

3. TypeScript 설정

TypeScript를 설치하고 tsconfig.json 파일을 설정합니다.

npm install --save-dev typescript

tsconfig.json 작성 시 최신 ES 모듈을 타깃으로 하며, 빌드 결과를 dist 폴더에 출력하도록 설정합니다.

{
  "compilerOptions": {
    "target": "es2022",
    "module": "NodeNext",
    "declaration": true,
    "outDir": "dist",
    "rootDir": "src",
    "strict": true
  }
}

소스 파일 작성 및 빌드 스크립트 설정합니다.

export const add = (a: number, b: number) => a + b;

 

{
  "scripts": {
    "build": "tsc"
  }
}

.gitignore 파일에 dist 폴더를 추가하여, 컴파일된 코드가 Git 리포지토리에 포함되지 않도록 합니다.

package.json에 CI 스크립트를 추가하여, CI에서 필요한 작업을 빠르게 실행할 수 있도록 설정합니다.

{
  "scripts": {
    "ci": "npm run build"
  }
}

4. Prettier 설정

Prettier는 코드를 일관된 스타일로 자동 포맷팅해주는 도구입니다.

npm install --save-dev prettier

.prettierrc 파일을 작성하여 기본 설정을 정의합니다.

{
  "semi": true,
  "singleQuote": true,
  "trailingComma": "all",
  "printWidth": 80,
  "tabWidth": 2
}

package.json에 Prettier 포맷팅 스크립트를 추가합니다.

{
  "scripts": {
    "format": "prettier --write ."
  }
}

아래 명령어로 프로젝트 내 모든 파일을 포맷팅 할 수 있습니다.

npm run format

package.json에 포맷이 제대로 적용되었는지 확인할 수 있는 스크립트를 추가합니다.

{
  "scripts": {
    "check-format": "prettier --check ."
  }
}

ci 스크립트에 포맷 체크를 추가하여 CI 과정에서도 코드 스타일이 일관되게 유지되도록 합니다.

{
  "scripts": {
    "ci": "npm run build && npm run check-format"
  }
}

5. @arethetypeswrong/cli로 exports 검사

@arethetypeswrong/cli를 설치하고, check-exports 스크립트를 설정하고 실행하며, main 필드를 추가한 후 다시 check-exports를 실행하고, 마지막으로 ci 스크립트에 이를 추가한 후 실행합니다.

( ++ @arethetypeswrong/cli는 패키지의 exports가 올바르게 설정되었는지 확인하는 도구이며, 이러한 설정은 실수하기 쉬우며, 잘못된 경우 패키지를 사용하는 사람들에게 문제가 발생할 수 있다고 함!! )

 

일단 설치 후 package.json 에 스크립트를 추가합니다.

npm install --save-dev @arethetypeswrong/cli

{
  "scripts": {
    "check-exports": "attw --pack ."
  }
}

check-exports 스크립트 실행합니다.

npm run check-exports

┌───────────────────┬──────────────────────┐
│                   │ "tt-package-demo"    │
├───────────────────┼──────────────────────┤
│ node10            │ 💀 Resolution failed │
├───────────────────┼──────────────────────┤
│ node16 (from CJS) │ 💀 Resolution failed │
├───────────────────┼──────────────────────┤
│ node16 (from ESM) │ 💀 Resolution failed │
├───────────────────┼──────────────────────┤
│ bundler           │ 💀 Resolution failed │
└───────────────────┴──────────────────────┘

위 결과는 현재 패키지가 어떤 버전의 Node나 번들러에서도 사용될 수 없다는 것을 의미합니다. 

다시 수정하여 package.json에 main 필드를 추가하여, Node.js가 패키지의 진입점을 찾을 수 있도록 합니다.

{
  "main": "dist/index.js"
}

이제 다시 exports 설정을 확인합니다.

npm run check-exports

┌───────────────────┬──────────────────────────────┐
│                   │ "tt-package-demo"            │
├───────────────────┼──────────────────────────────┤
│ node10            │ 🟢                           │
├───────────────────┼──────────────────────────────┤
│ node16 (from CJS) │ ⚠️ ESM (dynamic import only) │
├───────────────────┼──────────────────────────────┤
│ node16 (from ESM) │ 🟢 (ESM)                     │
├───────────────────┼──────────────────────────────┤
│ bundler           │ 🟢                           │
└───────────────────┴──────────────────────────────┘

이 메시지는 패키지가 ESM(ECMAScript Module) 형식에서 호환된다는 것을 의미합니다. CJS(CommonJS)를 사용하는 사람들은 동적 import로 패키지를 불러와야 합니다.

CJS(CommonJS)를 지원하지 않으려면 check-exports 스크립트를 다음과 같이 수정합니다. 

{
  "scripts": {
    "check-exports": "attw --pack . --ignore-rules=cjs-resolves-to-esm"
  }
}

┌───────────────────┬───────────────────┐
│                   │ "tt-package-demo" │
├───────────────────┼───────────────────┤
│ node10            │ 🟢                │
├───────────────────┼───────────────────┤
│ node16 (from CJS) │ 🟢 (ESM)          │
├───────────────────┼───────────────────┤
│ node16 (from ESM) │ 🟢 (ESM)          │
├───────────────────┼───────────────────┤
│ bundler           │ 🟢                │
└───────────────────┴───────────────────┘

ci 스크립트에 check-exports를 추가하여, 지속적 통합(CI) 프로세스에서 이 검사를 자동으로 실행하도록 설정합니다.

{
  "scripts": {
    "ci": "npm run build && npm run check-format && npm run check-exports"
  }
}

이 스크립트는 패키지 빌드, 코드 포맷 확인, exports 검사를 순차적으로 실행하게 됩니다.

6. tsup을 사용해 CJS와 ESM 동시 배포

tsup은 ES 모듈과 CommonJS를 동시에 배포할 수 있게 해주는 도구입니다. 해당 가이드는 기본적으로 ESM만 배포하도록 설정되어 있지만, CJS도 지원하려면 tsup을 사용할 수 있습니다.

일단 설치하고, 설정 파일을 생성합니다.

npm install --save-dev tsup

import { defineConfig } from "tsup";

export default defineConfig({
  entryPoints: ["src/index.ts"],
  // esm 모듈과 commonJS 빌드되도록 설정
  format: ["cjs", "esm"],
  dts: true,
  outDir: "dist",
  clean: true,
});

package.json의 빌드 스크립트를 tsc 대신 tsup을 사용하도록 변경합니다.

{
  "scripts": {
    "build": "tsup"
  }
}

package.json 에 exports 필드를 추가하여 CJS와 ESM 모듈을 각각 지원합니다.

{
  "exports": {
    "./package.json": "./package.json",
    ".": {
      "import": "./dist/index.js",
      "default": "./dist/index.cjs"
    }
  }
}

exports 검사를 다시 실행하여 모든 것이 정상적으로 설정되었는지 확인합니다.

npm run check-exports

tsup은 TypeScript 오류를 체크하지 않고 JavaScript로만 변환합니다. 이를 해결하기 위해 TypeScript를 린터로 사용할 수 있도록 설정합니다.

tsconfig.json 에 noEmit 필드를 추가합니다.

{
  "compilerOptions": {
    "noEmit": true
  }
}

tsconfig.json에서 tsup이 지원하는 기능들인 outDir, rootDir, sourceMap, declaration, declarationMap 필드를 제거합니다.

tsconfig.json에서 module을 Preserve로 변경하여 .js 확장자 없이도 사용할 수 있게 합니다.

{
  "compilerOptions": {
    "module": "Preserve"
  }
}

package.json에 TypeScript를 린터로 사용하는 스크립트를 추가합니다.

{
  "scripts": {
    "lint": "tsc"
  }
}

ci 스크립트에 lint를 추가하여 CI 과정에서 TypeScript 오류가 있는지 확인합니다.

{
  "scripts": {
    "ci": "npm run build && npm run check-format && npm run check-exports && npm run lint"
  }
}

7. Vitest로 테스트 설정

Vitest는 ESM과 TypeScript를 지원하는 테스트 도구입니다.

설치 + 테스트 파일 작성 + 테스트 스크립트 추가

npm install --save-dev vitest

import { add } from "./utils.js";
import { test, expect } from "vitest";

test("add", () => {
  expect(add(1, 2)).toBe(3);
});

{
  "scripts": {
    "test": "vitest run"
  }
}

개발 도중 테스트를 자동으로 실행하도록 dev 스크립트를 추가합니다.

{
  "scripts": {
    "dev": "vitest"
  }
}

ci 스크립트에 test를 추가하여, CI 과정에서 테스트가 항상 실행되도록 설정합니다.

{
  "scripts": {
    "ci": "npm run build && npm run check-format && npm run check-exports && npm run lint && npm run test"
  }
}

8. GitHub Actions로 CI 설정

GitHub Actions를 사용하면 코드를 푸시할 때마다 자동으로 CI(Continuous Integration) 프로세스를 실행할 수 있습니다.

.github/workflows/ci.yml 파일을 작성하여 기본 CI 프로세스를 설정합니다.

name: CI

on:
  pull_request:
  push:
    branches:
      - main

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  ci:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies
        run: npm install

      - name: Run CI
        run: npm run ci

• name: 워크플로우의 이름입니다.
• on: 워크플로우가 실행될 조건을 정의합니다. 여기서는 풀 리퀘스트 및 main 브랜치로의 푸시 시 실행됩니다.
• concurrency: 동일한 워크플로우가 중복 실행되는 것을 방지합니다.
• jobs: 실행할 작업들을 정의합니다.(ci 작업만 있습니다.)
  • actions/checkout@v4: 코드베이스를 체크아웃합니다.
  • actions/setup-node@v4: Node.js 환경을 설정합니다.
  • npm install: 프로젝트의 의존성을 설치합니다.
  • npm run ci: CI 스크립트를 실행합니다.

코드를 GitHub에 푸시한 후, GitHub 리포지토리의 Actions 탭에서 워크플로우가 성공적으로 실행되었는지 확인합니다.

9. Changesets로 버전 관리 및 배포

Changesets는 패키지의 버전 관리 및 배포를 자동화하는 도구입니다. 변경 사항을 쉽게 그룹화하여, NPM에 배포할 수 있습니다.

설치 + 초기화 및 기본 설정 파일 생성합니다.

npm install --save-dev @changesets/cli

npx changeset init

.changeset/config.json 파일을 열고, access 필드를 public으로 설정합니다.

이렇게 하면 Changesets가 NPM에 패키지를 배포할 수 있습니다.

{
  "access": "public"
}

.changeset/config.json 파일에서 commit 필드를 true로 설정합니다. 

( -> 버전 관리 후 변경 사항이 자동으로 커밋됩니다.)

{
  "commit": true
}

 

package.json에 local-release 스크립트(CI 과정을 실행하고, 패키지를 NPM에 배포)를 추가합니다. 

해당 스크립트는 로컬에서 새로운 버전을 배포할 때 사용됩니다.

{
  "scripts": {
    "local-release": "changeset version && changeset publish"
  }
}

package.json에 prepublishOnly 스크립트를 추가합니다. 이 스크립트는 NPM에 배포하기 전에 CI 과정을 자동으로 실행합니다.

이 설정은 사용자가 실수로 npm publish 명령어를 실행했을 때도, 미리 CI를 통해 검사를 수행하여 오류를 방지할 수 있습니다. 

{
  "scripts": {
    "prepublishOnly": "npm run ci"
  }
}

 

Changeset을 추가하여 변경 사항을 기록합니다.

npx changeset

이 명령어를 실행하면 인터랙티브 프롬프트가 열리고, 여기서 변경 사항을 그룹화하고 해당 릴리스를 패치 버전으로 지정할 수 있습니다. 예를 들어 "Initial release"라는 설명을 추가할 수 있습니다. -> 이 과정에서 .changeset 폴더에 새로운 Changeset 파일이 생성됩니다.

 

변경 사항을 커밋하여 저장소에 반영합니다.

git add .
git commit -m "Prepare for initial release"

NPM에 패키지를 배포합니다.

npm run local-release

NPM 레지스트리에서 패키지가 성공적으로 배포되었는지 확인합니다.

https://npmjs.com/package/<your-package-name>