NPM Package 생성 부터 배포 _진짜진짜최종🚀

 

 

사이드 프로젝트를 하면서 외부 라이브러리 사용을 하지말고 우리만의 라이브러리를 만들자고 하여

내가 맡게되었는데 ..

초보 개발자 입장에서는 도통 아무것도 모르겠고 어디서 부터 어떻게 시작하는지도 감이 안와서

여기저기 검색해보고 끌어모은 정보로 최종본을 만들게 되었다. 

이게 정답이라고는 할수 없지만 비슷한 상황이신 분들에게 도움이 되었으면 좋겠땨 🐥

 

🚀 NPM :

Node Package Manager로 이름의 유래는 npm이 Node.js용 패키지 관리자로 처음 생성되었을 때이다.

npm의 역할은 소프트웨어의 라이브러리 또는 레지스트리이다.

소프트웨어를 관리하고 설치를 지원하며 이 레지스트리에는 약 800,000개 이상의 npm 패키지가 포함되어있다.

오픈 소스 개발자는 이 npm을 이용하여 소프트웨어를 공유하고 관리한다.

• npm은 Node.js와 함께 설치된다. 그렇기 때문에 Node.js를 설치하면 npm 역시 같이 설치가 된다.

🚀 Package.json

npm의 패키지는 package.json에 정의된다. 

npm init 명령어를 통하면 최초에 이 파일이 만들어지고 npm 패키지를 설치하게 되면 이 package.json에 명시된다.

이 외에도 이 패키지가 이름이 무엇인지, 라이센스가 어떻게 되는지, NPM Repostory에 배포될 파일들이 무엇인지 등 패키지에 대한 정보를 명시한다. 보통 package.json을 가볍게 여기는 경우가 있는데 이 정보들은 단순하게 제공하는 것이 아닌 배포에 필요하고 패키지의 사용처를 남기는 등의 역할을 하므로 신중하게 작성할 필요가 있다.

Creating a package.json file | npm Docs

🚀 Package-lock.json

package-lock.json은 최초 npm init을 실행 시 생성되지는 않는다.

이 package-lock.json은 npm 패키지를 설치하거나 수정, 삭제 등의 작업을 진행할 때 생성되며 핵심 역할은 각 패키지에 대한 의존성 관리이다.

각 패키지는 서로 엉켜있는 실타래와 같다. 하나의 패키지를 여러 패키지에서 사용할 수 있고 하나의 패키지는 여러 개의 버전을 가지며 또 이 여러 버전을 다른 패키지에서 사용할 수 있다. 이렇게 되면 패키지 버전 간의 충돌과 호환이 되지 않는 경우가 있는데 이를 미연에 방지하기 위한 것이다.

 

실제로 package-lock.json을 살펴보면 하나의 패키지에 dependencies(종속)가 어떤 패키지인지 버전 정보와 이름이 나열되어 있고 dependencies에 명시된 특정 패키지를 다시 검색 및 추적하다 보면 여러 패키지에서 사용하는 것을 볼 수 있다.

간혹 내가 설치한 npm 패키지의 버전을 업데이트하기 위해 npm install을 하였는데 최신 버전이 업데이트되지 않는 경우에는 이 package-lock.json을 삭제하고 재 설치하자.

🚀 패키지 공유

npm 패키지는 NPM Registry에 배포하여 공유할 수 있다.

가입과 사용은 무료이고 일부 개인적인 권한을 확장하기 위해서는 요금을 부과해야 하지만 해당 포스팅을 따라 하는 데에는 불필요하다.

 

---

 

🔆 NPM 가입

 

npm

 

NPM Registry 가입은 NPM 공식 페이지에서 가입할 수 있다.

이름과 email, 비밀번호 입력 후 ⭐️email 인증을 필수로 진행⭐️해야 한다. 

email 인증을 하지 않으면 배포가 불가능하다.

가입 후 로그인을 하고 우측 상단의 아이콘을 눌러 Package 클릭

 

 

앞으로 패키지를 배포하게 되면 이곳에 올라가게 된다.

 

🔆 npm info

 

자신이 개발한 라이브러리를 배포하기전에, 배포가 가능한 패키지명인지 확인할 필요가 있다.

당연하지만, 현재 NPM에 배포된 라이브러리와 동일한 이름을 사용할 수 없다.

 

아래에 명령어를 사용하여 자신의 <패키지 이름>이 사용 가능한지 확인해 보자.

 

npm info <Package Name>

 

중복된 이름이라면 이미 배포된 패키지의 정보를 확인할수 있고,

중복되지 않은 이름이라면 404 에러가 발생 한다. 

✅ 404 에러가 나오면 생성할수 있는 패키지 이름 이다.

 

+추가로

이름을 바꾸고 싶지 않다면 패키지 이름 앞에 @스코프를 붙여준다.

예를들어, react 라는 패키지를 만들고 싶다면

@eunji/react

이렇게 본인 이름 또는 프로젝트 이름 등등 식별할수 있는 스코프를 지정해준다.

 

🔆 npm init

 

자신의 라이브러리를 NPM에 배포하기 위해서 NPM에 필요한 정보를 설정을 해주어야 한다.

자신의 라이브러리 폴더로 이동한 후, 터미널에 아래에 명령어를 실행해준다.

 

* 만들어둔 라이브러리가 없다면 <만들고자하는 라이브러리> 폴더를 생성하고,

내부에서 터미널 창을 연 후 아래와 같이 명령어를 입력하여 NPM 초기 설정을 진행하자.

 

# cd ProjectName
npm init

 

위의 명령어를 실행하면, 다음과 같은 화면을 볼 수 있다.

아래에 설명하는 내용은 추후에도 변경할 수 있으니 부담없이 진행하면 된다.

 

 

This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sensible defaults.

See `npm help init` for definitive documentation on these fields
and exactly what they do.

Use `npm install <pkg>` afterwards to install a package and
save it as a dependency in the package.json file.

Press ^C at any time to quit.
package name: (react-scroll-to-top)

 

폴더명을 기준으로 package name을 결정할지, 다른 이름으로 설정할지 물어봅니다.

위에서 npm info로 배포 가능한 이름을 찾아놓았고, 그 이름으로 입력해주면 됩니다.

 

version: (1.0.0)

 

그 다음, 버전을 물어봅니다.

버전은 기본적으로 major/ minor/ patch를 사용합니다.

이미 라이브러리 개발이 완료되었고, 배포만을 남겨둔 상황이라면 1.0.0을 그대로 사용하면 됩니다.

아직 개발중이고, 완벽하지 않다면 0.0.1을 지정하여 안정적인 버전이 아님을 명시합니다.

 

description:

 

라이브러리에 대한 설명을 작성하는 부분입니다. 자신의 라이브러리에 대한 설명을 작성합니다.

 

entry point: (index.js)

 

자신의 라이브러리를 다른 유저들이 사용할때 어떤파일이 입구파일이 되냐를 결정하는것이다.

보통은 index.js 이 디폴트값으로 되어있고 main.js 등등 원하는파일로 만들어도 된다.

* 단 해당파일은 .js 파일이여야 한다.

 

test command:

 

자신의 라이브러리를 테스트할 수 있는 테스트 명령어를 입력합니다.

테스트를 실행할 명령어가 없다면, Enter 키를 눌러 진행합니다.

 

git repository:

 

배포하려는 라이브러리의 소스코드를 확인할 수 있는 Git 저장소의 URL을 입력합니다.

URL이 존재하지 않다면 Enter 키를 눌러 진행합니다.

 

keywords:

 

배포하려는 패키지를 쉽게 알 수 있는 키워드를 입력합니다. 

해쉬태그# 같은 느낌이라고 보면됩니다. 이렇게 설정한 keyword는 npm search 사용 시 도움이 됩니다.

 

author:

 

배포하는 사람에 대한 정보를 입력합니다. 보통 Name <Email Address> 형식을 사용합니다.

 

license: (ISC)

 

배포하려는 라이브러리의 라이센스에 관한 질문입니다.

자신의 라이브러리의 라이센스에 맞게 작성합니다. ex) MIT, ISC 등

라이센스에 키워드에 관해서는 아래의 링크를 참고하시기 바랍니다.

 

Licensing a repository - GitHub Docs

 

이렇게 모든 항목을 입력하면 자신의 프로젝트 폴더안에 package.json 파일이 생성된 것을 확인할 수 있습니다.

 

🔆 npm login

 

NPM에 자신의 라이브러리를 배포하기 위해서는, 아래에 명령어를 사용하여 NPM 서비스에 로그인 할 필요가 있습니다.

 

npm login

 

위에 명령어를 실행하면 아래와 같이 로그인을 하기위한 절차가 실행됩니다.

 

Username: 
Password:
Email: (this IS public) 
Logged in as on https://registry.npmjs.org/.

 

위에서 생성한 NPM 계정의 정보를 입력하여 로그인합니다.

로그인을 하였다면 아래에 명령어를 실행하여 제대로 로그인되었는지 확인합니다.

 

npm whoami

 

Password 에는 암호화가 걸려있는건지.. 입력이 안되는것 처럼 보이지만 비밀번호 입력후 엔터 하면 Email로 넘어간댜..😮&zwj;💨

🔆 .npmignore

 

실제 개발에는 필요하나, 개발이 완료된 라이브러리를 사용할 때는 필요없는 파일들이 있습니다.

예를 들어 테스트 코드, 예제 소스들이 이에 해당할 수 있습니다.

이렇게 개발에는 필요하나, 배포에는 불필요한 파일들을 .npmignore 파일을 통해 제외 시킬 수 있습니다.

 

.idea
node_modules

 

개발하다가 추가된것들중 라이브러리를 사용할 때 필요없는 파일들이 있다면 추가해주면된다.

.npmignore파일은 .gitignore파일로도 대체가 가능하다.

 

🔆 npm publish

 

이제 NPM에 자신의 라이브러리를 배포할 준비가 되었습니다.

아래에 명령어를 통해 자신의 라이브러리를 NPM에 배포해 봅시다.

 

npm publish

 

라이브러리를 배포하기 전에 특정 명령어를 실행할 필요가 있다면 package.json을 수정합니다.

 

 

 

📝 만약 배포 중 오류가 출력되면 현재로는 보통 세 가지 경우이다.

 

1. NPM Registry 가입 후 E-Mail 인증을 하지 않은 경우

• E-Mail 인증을 시도하자.

2. 패키지의 이름이 이미 다른 패키지와 중복이 된 경우

• npm info <패키지이름> 으로 중복 확인후, package.json의 name 속성을 바꿔주자.

3. 이미 같은 버전으로 배포가 된 경우

• npm version [major, minor, path, x.x.x] 명령어로 버전을 올려 배포하자.

위 내용대로 하면 정상적으로 패키지가 배포되는 것을 확인할 수 있다.

 

 

✏️ 참고

배포된 패키지는 72시간이 지나면 삭제할 수 없어서 불필요한 패키지라면 미리 삭제하자.

 

npm unpublish <PACKAGE NAME> -f

 

🌱

이것으로 여러분이 개발한 라이브러리를 NPM에 배포하였습니다.

배포된 라이브러리를 사용하기 위해서는 여러분이 NPM 라이브러리를 사용하는 것과 동일하게 사용이 가능합니다.

 

npm install <Your Package Name>

 

🔆 npm Package 수정

 

NPM에 배포한 라이브러리를 수정하고 다시 배포해야할 일이 발생할 수 있습니다.

이렇게 재배포를 할 경우, 버전을 올려줄 필요가 있습니다.

버전을 올리기 위해서는 package.json 파일의 버전("version": "0.0.1")을 직접 수정하고 배포해도 되고,

아래에 명령어를 통해 버전을 업데이트할 수 있습니다.

 

npm version patch
npm version minor
npm version major

 

위에 명령어를 필요한 상황에 맞게 사용하시면, 쉽게 버전을 올릴 수 있습니다.

 

🔆 완료

 

이것으로 자신이 개발한 라이브러리를 NPM에 배포하는 방법에 대해서 알아보았습니다.

 

 

---

💡무조건 해야하는건 아니지만 참고할 내용💡

 

✅ 패키지의 구조 와 형식 참고

 

🔆 패키지 구조

 

다음과 같은 패키지 구조를 추천합니다.

• dist/는 배포용 디렉터리입니다. Webpack이나 Parcel, Gulp 같은 번들러로 배포용 파일을 생성할 수 있습니다.
• examples/는 제공할 예제 디렉터리입니다. 예제 파일과 함께 Demo 페이지를 제공한다면 더욱 좋습니다.
• lib/에는 패키지 제작을 위한 원본 파일이 포함되어 있습니다.

 

my_npm_module/
├── dist/
├── examples/
├── lib/
├── .gitignore
├── .npmignore
├── LICENSE
└── package.json

 

🔆 패키지 형식

 

다음 예시와 같이 AMD, UMD, CommonJS, ES Module 등의 제공할 패키지 형식을 지정합니다.

 

dist/
├── my_module.js        (UMD)
├── my_module.min.js    (UMD, compressed)
├── my_module.common.js (CommonJS, default)
└── my_module.esm.js    (ES Module)

 

 

✅ TypeScript 로 패키지를 만들때 참고

 

"scripts": {
  ...
  "prepare": "rm -rf dist && tsc"
},

 

Typescript로 라이브러리를 개발했다면, 배포전에 Typescript를 빌드할 필요가 있습니다.

이렇게 package.json의 scripts에 prepare 명령어를 선언하면, npm publish 명령어를 실행할 때, 해당 명령어를 실행하게 됩니다.

 

./tsconfig.json

{
  "compilerOptions": {
    "outDir" : "./dist/",
    "declaration": true,
    ...
  }
}

./package.json

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

./index.ts

export const 아무값 = "아무값"

 

이렇게 설정하면 tsc 명령어를 통해 컴파일된 ts 파일이 ./dist 폴더 아래에 js 파일 형태로 내보내진다.

즉 이 경우 index.ts 파일이 컴파일되 ./dist/index.js 파일로 내보내진다.

이를 npm 패키지로 받으면 package.json의 main값을 통해 진입점을 잡는 것이다.

참고로 타입스크립트 환경에서 패키지를 만든다면 그냥 index.js 파일만 내보내면 타입 추론이 불가능해지니 

declaration 옵션을 통해 d.ts 파일도 내보내야 한다. 이 파일이 있어야 패키지에서 typescript가 타입 추론을 해준다.

 

NPM 패키지를 typescript로 만들었다면 아마 ts 파일들과 컴파일된 파일들이 패키지에 공존할 텐데,

패키지를 사용할 때는 원본 ts 파일들은 필요가 없이 용량만 차지하게 된다.

이때 package.json에 files 필드를 이용해 특정 폴더만 내보낼 것이라고 지정하면 패키지를 내려받는 용량을 약간 개선할 수 있다.

 

또는 .gitignore, .npmignore 파일을 이용해서도 동일한 동작이 가능한데

일반적으로 files 설정이 가장 쉽기도 하고 복잡한 선택 구문이 필요한 일도 적기에

아마 대부분의 경우에는 이 설정만으로 충분할 거라 생각된다.

해당 설정을 어떻게 잡아야 하는지는 공식 문서를 참조하면 된다.

 

 

❤️ 도움주신분:

https://dev-yakuza.posstree.com/ko/share/deploy-npm-library/

https://kdydesign.github.io/2020/08/28/npm-tutorial/

https://www.youtube.com/watch?v=8-EPPMQMrgs&list=PLuHgQVnccGMB4krR04ug5nEXJ3sAEOWDL&index=3