🚀 npm 패키지 배포 도전기
오늘은 직접 만든 npm 패키지를 배포한 경험을 기록해 보려고 합니다. 이전에 제작을 준비했던 Zustand를 활용한 서버 상태 관리 미들웨어를 npm에 배포하면서 배운 점과 과정을 정리해 보겠습니다. 다음에 다시 사용할 때 참고할 수 있도록 자세하게 작성해 보겠습니다.
🛠️ npm 패키지란?
npm 패키지는 프로젝트에 간단히 설치해 다양하게 재사용할 수 있는 코드 모듈입니다.
- public으로 설정하면 누구나 설치하고 사용할 수 있습니다.
- 의존성 관리와 배포는 npm 레지스트리를 통해 간편하게 이루어집니다.
이번에 만든 상태 관리 미들웨어 역시 같은 방식으로 배포했어요. 생각보다 과정이 간단하더라고요. 😎
🏗️ 프로젝트 구조 설정
1. Vite 프로젝트 생성
우선 Vite를 통해 간단한 프로젝트를 만들고, src 폴더 내부에 index.ts 파일을 생성해 재사용할 코드를 작성했습니다.
2. package.json 설정
배포를 위해 package.json 파일을 수정했습니다. 아래는 기본적인 예제입니다.
{
"name": "example",
"version": "0.0.0",
"description": "A Vite-based TS example package",
"license": "MIT",
"type": "module",
"private": false,
"main": "dist/index.cjs", // CommonJS 빌드 결과물 진입점
"module": "dist/index.js", // ES Module 빌드 결과물 진입점
"types": "dist/index.d.ts", // 타입 선언 파일 진입점
"scripts": {
"build": "vite build", // vite.config.ts를 이용해 빌드
"publish:patch": "npm version patch && npm publish",
"publish:minor": "npm version minor && npm publish",
"publish:major": "npm version major && npm publish"
},
"repository": {
"type": "git",
"url": "https://github.com/repository"
},
"homepage": "https://homepage.com/",
"keywords": [
"vite",
"typescript",
"example",
"npm-publish"
],
"peerDependencies": {
"react": "^18.0.0"
}
}💡 주요 설정 포인트:
✅ name → npm에 명시되는 패키지 이름
✅ version → 시멘틱 버저닝 준수
✅ main, module, types → 각각 빌드 결과물의 진입점 설정
✅ peerDependencies → 패키지 사용자에게 설치가 필요한 패키지 명시
3. tsconfig 및 vite.config 설정
tsconfig는 거의 수정할 게 없었지만, vite.config.ts는 조금 복잡했습니다.
터미널에서 다음 패키지를 설치해 주세요.
npm install -D path @types/node vite-plugin-dts그런 후 vite.config.ts에 다음과 같이 설정합니다.
import * as path from "path";
import { defineConfig } from "vite";
import dts from "vite-plugin-dts";
export default defineConfig({
build: {
lib: {
entry: path.resolve(__dirname, "src/index.ts"),
name: "index",
fileName: "index",
formats: ["es", "cjs"],
},
rollupOptions: {
external: ["react"], // react 가 없다면 안써도 됨
output: {
globals: {
react: "React"
}
}
},
commonjsOptions: {
esmExternals: ["react"]
}
},
plugins: [dts()]
});💡 주요 설정 포인트:
✅ formats → ES Module, CommonJS로 각각 빌드
✅ external → 외부 라이브러리 설정 (react 같은 경우)
✅ dts() → 타입 선언 파일 생성
4. LICENSE 파일 작성
라이선스 파일도 추가해야 합니다. 보통 MIT 라이선스를 많이 사용하죠.
The MIT License (MIT)
Copyright (c) <year> <copyright holders>
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
...📌 연도와 저작권 소유자를 수정해 주면 됩니다.
5. .npmignore 설정
.gitignore처럼 배포할 때 제외할 파일을 설정할 수 있습니다.
.npmignore 파일을 만들어 다음과 같이 작성합니다.
node_modules
dist
.vscode🚀 배포 과정
- npm에 가입 후, 터미널에서 로그인합니다.
npm adduser- 다음 명령어로 배포합니다.
npm publish✅ 주의사항
- 패키지 이름은 고유해야 합니다.
- 대문자(UpperCase) 사용이 불가합니다.
- 공개 패키지는 --access=public 옵션이 필요할 수 있습니다.
npm publish --access=public💡 느낀 점
npm 패키지 배포는 실무에서만 쓰이는 어려운 작업이라고 생각했는데, 생각보다 간단하게 할 수 있었습니다. 직접 만든 작은 라이브러리를 패키지화하고 배포까지 완료하니 뿌듯하더라고요. 😎
또, zustand와 TanStack Query 기반의 상태 관리 미들웨어를 더욱 고도화해서 팀원들과 함께 효율적으로 사용할 생각에 기대가 큽니다. 앞으로 상태 관리에서 더 발전된 기술을 시도해 보고 싶습니다!
🎯 마무리 한 줄
“작은 성취가 큰 자신감을 만든다.”
이번 npm 패키지 배포는 제게 작은 성취였지만, 앞으로의 개발에 큰 자신감이 될 것 같습니다. 다음에는 더 완성도 높은 패키지를 만들어 배포해 보고 싶습니다. 😎🔥
📌 Next.js + Zustand + TanStack Query 기반 상태 관리 패키지 = 다음 도전 목표! 💪
