간단한 TS 유틸리티 함수 패키지를 NPM에 배포하기

발단

디렉토리 설정

// common-utils.ts

export function isEmptyArray() { ... }
export function isNotEmptyArray() { ... }

common-utils
  - src
    - index.ts // 모듈 진입점
    - common-utils.ts // 모듈 정의 파일
  - .gitignore // GitHub 에 올리지 않을 파일들을 명시
  - .npmignore // NPM 에 올리지 않을 파일들을 명시

package.json 및 README.md 설정

$ npm init --scope=einere

{
  "name": "@einere/common-utils",
  "version": "1.0.0",
  "description": "Einere's common utilities",
  "type": "module", // 해당 패키지가 ESM을 사용하도록 지정합니다.
  "main": "./dist/index.js", // 패키지의 진입점입니다.
  "types": "./dist/index.d.ts", // 패키지의 타입 정의 파일의 위치입니다.
  "files": [
    "dist" // npm 배포 시 'dist' 폴더의 내용만 포함합니다.
  ],
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc",
    "prepublishOnly": "npm run build", // npm에 배포하기 직전, 빌드를 합니다.
  },
  "publishConfig": {
    "access": "public" // NPM에 배포하기 위해서는 공개로 지정해야 합니다.
  },
  "devDependencies": {
    "typescript": "^5.8.3"
  },
  // ...
}

진입점 구현

// index.ts
export * from './common-utils.js';

// 빌드 결과물
dist
  - index.d.ts
  - index.js
  - common-utils.d.ts
  - common-utils.js

// dist/index.js
export * from "./common-utils.js"; // 이 경우에는 제대로 유틸리티 함수를 가져옵니다.

// dist/index.d.ts
// d.ts 파일은 TSC에 의해 확장자 변경이 이루어지지 않습니다.
// 결국, 존재하지 않는 ts 파일을 가져오려고 합니다.
export * from "./common-utils.ts"; 

Typescript 설정

$ npm install -D typescript

{
  // 컴파일 과정과 그 결과물에 대한 설정들입니다.
  "compilerOptions": {
    "target": "ESNext", // 결과물의 JS 버전을 최신 버전으로 지정합니다.
    "module": "ESNext", // 결과물의 모듈 시스템을 ESM로 지정합니다.
    "moduleResolution": "node10", // 컴파일 시, 모듈 해석 방식을 지정합니다.
    "esModuleInterop": true, // CJS 모듈을 ESM 방식으로 import 할 수 있도록 돕습니다.
    "forceConsistentCasingInFileNames": true,
    "strict": true, // 엄격한 타입 체크
    "skipLibCheck": true, // 라이브러리의 타입 체크를 건너뜁니다.
    "declaration": true, // .d.ts 타입 정의 파일을 생성합니다.
    "outDir": "./dist", // 빌드 결과물이 저장될 디렉토리를 지정합니다.
    "rootDir": "./src"
  },
  "include": [
    "src/**/*.ts" // src 폴더 내의 모든 .ts 파일을 컴파일 대상에 포함합니다.
  ],
  "exclude": [
    "node_modules",
    "dist" // dist 폴더는 컴파일 대상에서 제외합니다.
  ]
}

빌드

$ npm install && npm run build

dist
  - index.d.ts
  - index.js
  - common-utils.d.ts
  - common-utils.js

// dist/index.js
export * from './common-utils.js';

// dist/index.d.ts
export * from "./common-utils.js"; // js 파일을 가져오게끔 되어있음에 유의!

로컬 테스트

$ cd .. && mkdir common-utils-playground && cd common-utils-playground

// common-utils-playground/package.json
{
  "name": "common-utils-playground",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "build": "npx tsc",
    "start": "node dist/index.js"
  },
  "devDependencies": {
    "typescript": "^5.8.3"
  },
  "type": "module" // ESM을 사용합니다.
}

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "node10",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "rootDir": "."
  },
  "include": ["./**/*.ts"],
  "exclude": ["node_modules"]
}

$ cd ../common-utils
$ npm link

$ cd ../common-utils-playground
$ npm install
$ npm link @einere/common-utils

// index.ts
import { isEmptyArray, isNotEmptyArray } from '@einere/common-utils';


if(isEmptyArray([])) {
  console.debug('foo!')
}

if(isNotEmptyArray([1, 2])) {
  console.debug('bar!')
}

$ npm run build && npm run start
foo!
bar!

NPM에 배포하기

$ npm login
$ npm publish

npm notice 
npm notice 📦  @einere/common-utils@1.0.0
npm notice === Tarball Contents === 
npm notice 0B    README.md             
npm notice 2.3kB dist/common-utils.d.ts
npm notice 4.3kB dist/common-utils.js  
npm notice 35B   dist/index.d.ts       
npm notice 35B   dist/index.js         
npm notice 906B  package.json          
npm notice === Tarball Details === 
npm notice name:          @einere/common-utils                    
npm notice version:       1.0.0                                   
npm notice filename:      einere-common-utils-1.0.0.tgz           
npm notice package size:  2.6 kB                                  
npm notice unpacked size: 7.5 kB                                  

// ...

Press ENTER to open in the browser...

+ @einere/common-utils@1.0.0

import { isEmptyArray } from "@einere/common-utils";

export default function HomePage() {
  if (isEmptyArray([])) {
    console.log("foo");
  }
  // ...
 }

참고

후기