안녕하세요. J4J입니다.
이번 포스팅은 npm 패키지 배포하는 방법에 대해 적어보는 시간을 가져보려고 합니다.
NPM 패키지 배포
npm 패키지 배포라고 하는 것은 한 번 만들어진 javascript 기반의 라이브러리, 모듈 등을 다양한 개발 프로젝트에 개발자들이 활용할 수 있도록 저장소에 등록하는 과정입니다.
개발 공부를 하게 되면서 많이 시도하는 것 중 하나는 패키지를 설치하는 것이라고 얘기할 수 있습니다.
다음과 같은 명령어를 이용하여 react, typescript, dayjs 등과 같은 패키지들을 많이 설치해 보셨을 것 같은데, 이런 패키지들도 결국 누군가가 npm이라는 패키지 저장소에 올려둔 라이브러리입니다.
$ npm install { package 명 }
npm에 패키지를 배포하는 것은 특정 누군가만 수행할 수 있는 것이 아니라, 누구나 배포해 볼 수 있습니다.
대표적으로 https://www.npmjs.com와 같은 공식 registry를 많이 사용해 볼 수 있고, 회사 내부에 registry 저장소가 별도로 구축되어 있다면 별도의 설정을 통해 사내 registry에도 배포를 해볼 수 있습니다.
실제로 저도 팀 내부에 있는 모든 애플리케이션에서 사용되어야 하는 모듈들을 구성하여 사내 registry에 배포를 하는 작업들을 많이 수행했었습니다.
그 결과로 모든 서비스마다 구성되어야 하는 공통 설정, 함수들을 매번 설정하지 않고 패키지를 설치하는 행위 한 번으로 어디서든 사용할 수 있는 구조로 변경할 수 있었습니다.
이처럼 내부 아키텍처를 구축할 때 npm 기반의 패키지를 배포하여 관리하는 것은 상황에 따라 효과적인 결과를 만들어 낼 수 있으니, 사용성을 판단하여 누구나 적용해볼 수 있습니다.
배포할 프로젝트 구성
이제는 실제로 패키지로 배포될 프로젝트를 구성하여 npm에 올려보도록 하겠습니다.
npm에 올라가는 프로젝트라고 다른 js 기반의 프로젝트와 구조가 크게 다르지 않지만, 배포를 위한 별도의 설정이 필수적으로 들어가야 합니다.
프로젝트를 구성하는 방법에 대해 가볍게 작성해 보겠습니다.
[ 1. package.json 초기화 ]
npm에 배포되는 프로젝트의 많은 설정들을 담당하는 곳이 package.json입니다.
패키지의 버전 관리부터, 어떤 파일들을 npm에 배포할 것인지 등 다양한 설정들이 모두 package.json에 관리되고는 합니다.
package.json 파일을 수동으로 생성을 해주셔도 되고, 다음 명령어를 이용하여 package.json 파일을 생성해 줄 수 있습니다.
$ npm init -y
[ 2. 배포 모듈 구성 ]
패키지를 설치하는 프로젝트에서 사용되어야 하는 모듈들을 구성해 보겠습니다.
각자 필요한 모듈들을 구성해 주시면 되고, 샘플로 다음과 같이 barrel 기반의 구조를 잡아봤습니다.
// /src/prints/print.js
/**
* 애플리케이션이 초기화 되었을 때 로그 출력
*/
export const initPrint = () => {
console.log('애플리케이션이 실행되었습니다...');
}
// /src/prints/index.js
export { initPrint } from './print';
// /src/utils/calc.js
/**
* parameter로 전달 받은 두 개의 값을 더한 결과를 반환한다.
*/
export const sum = (a, b) => a + b;
/**
* parameter로 전달 받은 두 개의 값을 곱한 결과를 반환한다.
*/
export const multiple = (a, b) => a * b;
// /src/utils/index.js
export { multiple, sum } from './calc';
// /src/index.js
export * from './prints';
export * from './utils';
[ 3. package.json 배포 설정 ]
package.json은 다음과 같이 작성할 수 있습니다.
작성되는 방식은 어떤 프로젝트 구조에서 배포하냐에 따라 설정이 조금씩 달라지고, 아래 방식의 경우는 js만 사용되고 build 하는 과정 없이 배포할 때 설정할 수 있는 정말 간단한 방법입니다.
만약, react와 typescript 등이 사용되는 곳에서는 설정 방식이 달라진다는 점을 참고해 주셔야 합니다.
// package.json
{
"name": "@jforj26/npm-deploy", // 배포되는 패키지 명
"version": "1.0.0", // 배포되는 버전
"description": "npm deploy 테스트를 위한 패키지", // 배포되는 패키지 설명
"exports": {
".": "./src/index.js" // 패키지를 require/import 할 때 사용되는 파일
},
"files": ["src"], // 배포되는 파일/폴더
"keywords": [ // 패키지가 노출될 수 있는 keyword 구성
"print",
"util"
],
"author": "jforj", // 저작권자 설정
"license": "ISC", // 라이센스 설정
"publishConfig": {
"access": "public" // public 기반으로 package 접근 가능하도록 설정
}
}
NPM 패키지 저장소 구성
프로젝트 구성이 되었다면, 배포할 npm 패키지의 저장소를 위한 구성이 되어야 합니다.
사실 저장소의 경우에는 결국 계정 정보만 존재해도 바로 배포를 할 수 있습니다.
그래서 https://www.npmjs.com에 접속하여 계정이 없으신 분들은 계정을 생성해 주시면 됩니다.
계정이 생성되신 분들은 다음 순서대로 organization, token을 추가합니다.
[ 1. profile을 통해 organization add ]
[ 2. organization 상세 정보 입력 ]
organization의 경우 패키지의 이름이 함께 사용되는 정보입니다.
저의 경우 위에 package.json에 작성할 때 @jforj26과 같은 prefix를 패키지 명에 구성했는데, @을 제외한 정보가 organization의 정보로 사용되어야 합니다.
그래서 저는 다음과 같이 organization을 구성해 봤습니다.
[ 3. 생성 확인 ]
추가적인 멤버 설정은 skip을 해주면 최종적으로 다음과 같이 organization이 생성됩니다.
[ 4. profile을 통해 access token 접근 ]
token 없이 사용하는 다른 방법도 있지만, 다른 방법을 사용하지 않는 경우에는 인증 token이 별도로 필요합니다.
token을 만들기 위해서는 다음과 같이 profile을 통해 관리 페이지로 먼저 이동합니다.
[ 5. access token 생성 ]
new token 버튼을 클릭한 뒤 token에 대한 상세 정보를 입력하여 생성해 줍니다.
two-factor 설정은 필수이며, 권한과 만료 기한 같은 경우 자유롭게 적용해 주시면 됩니다.
token이 최종적으로 만들어졌다면 token 정보를 백업하여 관리해 주시고, 구성된 프로젝트를 이용하여 배포해 보겠습니다.
NPM 패키지 배포
프로젝트 디렉토리로 넘어와서 다음과 같은 순서대로 패키지를 배포해 보겠습니다.
[ 1. npm login ]
다음 명령어를 입력하여 로그인을 해줍니다.
명령어를 입력하면 브라우저 기반으로 인증하는 화면이 나올 것이고, 생성했던 계정으로 인증을 수행해 주시면 됩니다.
$ npm login
[ 2. token 설정 ]
다음 명령어를 입력하여 access token 설정을 해줍니다.
$ npm config set //registry.npmjs.org/:_authToken={ token 값 }
[ 3. 배포 ]
publish 명령어를 통해 배포를 진행합니다.
$ npm publish
[ 4. 배포 확인 ]
배포가 올바르게 되었다면 다음과 같이 organization package 정보에서 확인이 가능합니다.
또한 다른 패키지들을 설치하는 것처럼 사용하고자 하는 프로젝트에 설치를 한 뒤 사용해 볼 수도 있습니다.
$ npm install { 패키지 명 }
// 패키지 사용되는 파일
import { sum } from '@jforj26/npm-deploy';
export default function App() {
console.log(sum(3, 5));
...
}
패키지 배포에 영향을 주는 파일
[ 1. .npmrc ]
.npmrc 의 경우 npm 배포에 사용되는 설정 정보들을 담아둘 수 있는 파일입니다.
예를 들어, 방금처럼 authToken에 대한 설정을 명령어로 하지 않고 .npmrc에서 관리할 수 있고 또는 사내 registry를 사용하는 경우 registry 정보 작성 등의 적용을 할 수 있습니다.
.npmrc의 경우 프로젝트 가장 상위에 생성하면 되고 다음과 같이 필요한 설정을 이곳에 담아볼 수 있습니다.
// .npmrc
registry={ registry 도메인 }
//registry.npmjs.org/:_authToken={ token 값 }
[ 2. .npmignore ]
.npmignore 같은 경우는 .gitignore와 유사하게 배포를 할 때 예외 처리가 되어야 하는 파일 경로들을 관리합니다.
이 또한 프로젝트 가장 상위에 생성되어야 하며, 한 가지 유의 사항으로는 package.json에 files의 경로로 포함시킨 곳은 .npmignore에 등록하더라도 예외가 되지 않는 것입니다.
그래서 이 부분을 고려하여 ignore 설정을 진행해 주시면 되고, 다음과 같이 작성을 해볼 수 있습니다.
// .npmignore
src/unpackages/
*.log
[ 3. README.md ]
README.md의 경우 npm에 배포된 패키지의 상세 정보에 노출시켜 패키지에 대한 설명을 담을 수 있습니다.
git에서 사용하던 것과 동일하게 프로젝트 상위에 다음과 같이 README.md를 작성해 보면, 패키지의 상세 정보에 이렇게 노출되는 것을 확인할 수 있습니다.
// README.md
## Getting Started
```
$ npm install @jforj/npm-deploy
```
## Baisc Usage
package에서 제공하는 기능은 2가지가 존재합니다.
* print
* util
<br />
print에는 상황에 따라 출력할 수 있는 함수들을 제공합니다. <br />
util에는 계산 처리를 도와주는 함수들을 제공합니다. <br /><br />
계산 처리를 해야 하는 경우에는 다음과 같이 사용해 볼 수 있습니다.
```
import { sum } from '@jforj/npm-deploy'
function basic() {
const result = sum(3, 5); // result의 결과는 8이 됩니다.
...
}
```
패키지의 버전 관리
npm의 패키지에서는 semVer이라는 버전 관리 방식이 사용됩니다.
semVer은 다음과 같은 구조가 띄는 것을 의미합니다.
"[major].[minor].[patch]"
major는 이전 버전과 호환되지 않는 새로운 기능 변경이 발생되는 것을 의미합니다.
그래서 major 버전이 변경되었다는 것은 기존 사용 방식이 그대로 적용되지 않는 기능들도 존재할 수 있게 됩니다.
minor는 이전 버전과 호환이 되면서 새로운 기능이 생긴 것을 의미합니다.
그러므로 버전을 높일 때 새로운 기능에 대해서만 고려하며 적용할 수 있습니다.
patch의 주요 변경 점은 버그 수정입니다.
새로운 기능이 생긴 것보다는, 기존 기능에 버그가 발생된 것들이 수정된 것에 초점이 맞춰진 버전 변경입니다.
그래서 패키지에 배포를 할 때마다 우리가 해줘야 하는 행동은 package.json에 버전 정보를 변경하여 publish 명령어를 수행하는 것입니다.
기존에 사용되고 있는 버전에 그대로 배포를 하는 것은 불가능하기에, 어떤 변경점이 발생되었는지를 확인한 뒤 버전을 높여 배포를 해줘야 합니다.
그리고 이러한 버전 관리를 돕는 다양한 도구들이 이미 존재하고 있습니다.
Semantic Release로 자동 버전 관리하기: GitLab 파이프라인 구성과 같은 글을 참고하시면 자동으로 버전 관리를 도와주는 설정 방식을 적용해볼 수 있습니다.
Semantic Release로 자동 버전 관리하기: GitLab 파이프라인 구성
안녕하세요. J4J입니다. 이번 포스팅은 semantic release로 자동 버전 관리하는 방법에 대해 적어보는 시간을 가져보려고 합니다. Semantic Release semantic release는 commit 메시지를 분석하여 자동으로 소프
jforj.tistory.com
패키지 자동 배포
devops 기반의 자동화 관리가 이루어지는 요즘 패키지 배포 또한 자동화 관리가 이루어지는 방식을 많이 채택합니다.
우리가 많이 사용하는 github action, gitlab ci 등의 설정을 통해서 자동화 관리를 적용 해볼 수 있고, 적용 방식 또한 매우 간단합니다.
단순하게 gitlab-ci.yml 파일로 샘플을 보여주면 다음과 같습니다.
// .gitlab-ci.yml
stages:
- publish
# publish 자동화
publish:
image: node:20
stage: publish
script:
- npm config set //registry.npmjs.org/:_authToken={ token 값 }
- npm publish
기존에 로컬 환경에서 배포를 하기 위해 입력해던 명령어들을 그대로 script를 활용하여 적용할 수 있습니다.
다만, token 정보는 노출이 지양되는 정보이기 때문에 gitlab variable 설정 등을 통해 최대한 안전하게 사용할 수 있도록 적용해 주시면 됩니다.
만약, github action을 이용하시는 분들이라면 npm 계정과 github을 연동하여 token 없이 자동화 배포 하는 방식을 선택하는 것을 권장하는 바입니다.
그러므로 어떤 환경에서 배포하는지에 따라 적절하게 선택해 주시면 될 것 같습니다.
이상으로 npm 패키지 배포하는 방법에 대해 간단하게 알아보는 시간이었습니다.
읽어주셔서 감사합니다.
'Language > JavaScript' 카테고리의 다른 글
| [JavaScript] 비동기 처리와 Callback, Promise, Async/Await (0) | 2021.06.29 |
|---|---|
| [JavaScript] 클로저 (Closure) (0) | 2021.06.22 |
| [JavaScript] This와 Call, Apply, Bind (0) | 2021.06.21 |
| [JavaScript] Lexical Scope (0) | 2021.06.20 |
| [JavaScript] 실행 문맥 (Execution Context) (0) | 2021.06.20 |
댓글