[npm] npm에 내 package 배포하기 (feat. npx)

최종 결과물 👇

https://www.npmjs.com/package/ktmihs-bp

ktmihs-bp

https://github.com/ktmihs/boilerplate/tree/main/ktmihs-bp

GitHub - ktmihs/boilerplate: react boilerplate

 

만들어 둔 boilerplate를 매번 git clone을 통해 다운로드하고, git을 수정하는 것이 꽤나 번거롭다고 생각되었다. 그래서 다른 방법이 있을지 찾아보다가 npm에 내 boilerplate를 package처럼 등록하면 보다 효율적으로 boilerplate를 사용할 수 있을 것 같았다.

npx 명령어를 사용하면 매번 github에 들어가서 주소를 복사해 clone 한 후, .git을 지우는 번거로운 작업을 한 줄로 대체할 수 있고, 이 기회에 npm과 npx에 대해 학습할 목적으로 진행하게 되었다.

생각보다 어렵지 않았고 재밌게 진행하였다. 고고🕵️‍♂️

 

npm 등록 패키지 생성

우선 npm에 등록할 패키지를 생성해보자.

npm에 등록할 패키지를 github repository로 생성해 준다.

내 경우에는 이미 생성해둔 boilerplate의 main branch에 폴더를 생성해 주었다.

install할 package가 있는 repository에 추가해두었다.

각 브랜치마다 다른 boilerplate가 존재하고, 해당 브랜치에서 내가 입력한 프로젝트 명으로 clone 할 예정이다.

 

이제 npm에 올릴 package를 구성해 보자.

업로드할 폴더를 생성하고, 폴더 안에서 npm init을 한다.

$ mkdir ktmihs-bp
$ cd ktmihs-bp

$ npm init -y

 

그리고 생성된 package.json을 본인의 상황에 맞게 수정한다.

{
  "name": "ktmihs-bp",
  "version": "1.0.0",
  "description": "관련 설명 작성하기",
  "bin": {
    "ktmihs-bp": "./bin/generate.js"		// 아래 설명을 참고
  },
  "keywords": [		// 관련 keywords를 작성
    "react",
    "node",
    "boilerplate",
    "typescript",
    "vite",
    "webpack"
  ],
  "author": "MY_NAME <MY_EMAIL> (MY_PAGE)",	// 작성자 관련 정보
  "license": "ISC",
  "homepage": "https://github.com/ktmihs/boilerplate",	// 관련 homepage
  "repository": {		// repository 정보
    "type": "git",
    "url": "https://github.com/ktmihs/boilerplate.git"
  },
  "bugs": {		// bug 관련 알림 받을 곳
    "url": "https://github.com/ktmihs/boilerplate/issues",
    "email": "EMAIL"
  }
}

- package.json

 

cli 명령어 추가하기

https://ktmihs.tistory.com/entry/Nodejs-CLI-%EB%AA%85%EB%A0%B9%EC%96%B4-%EC%82%AC%EC%9A%A9%ED%95%98%EA%B8%B0

[Node.js] CLI 명령어 사용하기

이전에 작성한 cli 명령어 포스팅을 참고하여 사용할 명령어를 추가해 보자.

이번에는 이를 사용하여 추가한 명령어로 특정 package(branch)를 선택하고, 입력한 프로젝트 명으로 새로운 폴더에 프로젝트를 설치할 예정이다.

위에서 작성한 대로, 설치 로직이 작성된 스크립트를 실행하는 명령어를 추가한다.

{
  "bin": {
    "ktmihs-bp": "./bin/generate.js"		// 폴더 명과 같은 'ktmihs-bp'라는 명령어를 사용할 예정
  },
}

- package.json

 

script 생성하기

상단에서 설명했듯, 설정한 명령어를 통해 script 파일을 실행할 수 있다.

나의 경우에는, 폴더명과 같은 "ktmihs-bp" 명령어로 bin 폴더 내의 generate.js 파일을 실행할 예정이다.

{
  "bin": {
    "ktmihs-bp": "./bin/generate.js"
  }
}

- package.json의 bin

 

이제 generate.js script 파일을 생성해 보자.

#! /usr/bin/env node

import { execSync } from "child_process";
import { existsSync } from "fs";

// 내가 다운 받을 패키지 종류 (나의 경우에는 branch 별로 각 패키지 이름을 동일시 해주었다.)
const MY_PACKAGE_LIST = ["react-webpack-ts", "react-vite-ts"];
const EXIT = () => process.exit(1);

// 패키지 종류 출력 함수
const printPackage = () => {
  console.log("package list :");
  MY_PACKAGE_LIST.forEach((PACKAGE_NAME, idx) =>
    console.log(`    ${idx + 1}. ${PACKAGE_NAME}`)
  )
}

// 예제 출력 함수
const printExample = () => {
  console.log("For example :");
  console.log("    npx ktmihs-bp react-webpack-ts my-app");
}

// 명령어 입력 개수에 따라 예외 처리
if (process.argv.length < 3) {
  console.log("You have to provide a selected package's name.");

  printPackage();
  printExample();
  EXIT();
}

if (process.argv.length < 4) {
  console.log("You have to provide a name to your app.");

  printExample();
  EXIT();
}

const PACKAGE_NAME = process.argv[2];
const PROJECT_NAME = process.argv[3];
const GIT_REPO = 'https://github.com/ktmihs/boilerplate';

// 존재하지 않는 패키지 설치를 시도할 경우의 예외처리
if (!MY_PACKAGE_LIST.includes(PACKAGE_NAME)) {
  console.log(`The package ${PACKAGE_NAME} doesn't exist.`);
  console.log(`You can download this packages.`);

  printPackage();
  EXIT();
}

우선 예외 처리를 해주었다. 명령어를 원하는 양식대로 작성하지 않았을 경우, 입력 방법을 알려주고 종료시키도록 하였다.

또한 나의 경우에는 repository가 아래와 같이 구성되어 있다. 

main branch - 실행 script

react-webpack-ts branch - "react-webpack-ts" package

react-vite-ts branch - "react-vite-ts" package

 

그리고 아래 메인 실행 로직에서 이 브랜치를 선택하여 해당 브랜치의 코드를 내가 지정한 새로운 프로젝트로 clone 할 예정이다.

이를 참고하여 본인의 상황에 맞게 작성해주면 될 것이다.

// IIFE
(async () => {
  try {
    const isExistProject = existsSync(PROJECT_NAME);

	// 이미 존재하는 프로젝트일 경우, 예외 처리
    if (isExistProject) {
      console.log(
        `The file ${PROJECT_NAME} already exist in the current directory, please give it another name.`
      );

      EXIT();
    }

	// 예외 처리 후, 메인 로직 실행
    console.log("Downloading files...");
    // degit 관련 설명은 하단에 첨부
    execSync(`npx degit ${GIT_REPO}/${PACKAGE_NAME}#${PACKAGE_NAME} ${PROJECT_NAME}`);

	// 설치된 후, 해당 프로젝트로 들어가 설치를 해줌
    console.log("\nInstalling dependencies...");
    process.chdir(PROJECT_NAME);
    execSync("npm install");

    console.log("\n\n🐰 The installation is done! 🐰\n");
  } catch (error) {
    console.log(error);
  }
})();

 

위에서 `git clone` 대신 `degit`을 사용해 보았다. git clone을 사용해도 무방하다.

나는 특정 branch 안의 특정 폴더를 받고 싶었기 때문에, degit을 사용하여 clone 했을 때보다 depth를 줄였다.

 

git clone을 사용했을 때에는

my-new-project > boilerplate > react-webpack-ts > 내부 로직

처럼 깊어졌다면,

degit으로 특정 폴더를 선택했을 때는,

my-new-project > 내부 로직

로 내가 원하던 대로 설치할 수 있었다. 아래 글을 참고해도 된다.

https://ktmihs.tistory.com/entry/git-git-clone-%EB%8C%80%EC%8B%A0-degit-%EC%82%AC%EC%9A%A9%ED%95%98%EA%B8%B0

[git] git clone 대신 degit 사용하기

 

script가 제대로 작동하는지 확인하고 싶다면, `npm -g i`로 최신화해준 후, bin에 작성한 명령어로 실행을 해보면 된다.

모든 예외처리를 확인한 후, npm에 등록하는 것이 좋을 것 같다.

 

이제 script도 모두 작성하였으니, 본격적으로 npm에 등록해 보자!

 

npm 등록하기

npm에 등록하는 것 자체는 생각보다 간단하다.

우선 npm 계정이 없다면 회원가입을 해준다.

회원가입 후, 로컬에서 아래 명령어로 로그인을 해준다.

$ npm login

 

회원가입 시 작성한 name, email, password를 입력하면 로그인이 완료된다.

로그인 후, 등록할 package가 있는 폴더에서 아래 명령어로 package를 발행하면 끝!

$ npm publish

 

이렇게 하면 npm에서 내 packages에서 발행된 package를 확인할 수 있다.

npm packages

 

이후, 수정을 하게 되면 package.json의 version을 수정한 후, 다시 publish를 하면 버전업된 결과물이 반영된다.

 

내 package 사용하기

이제 등록된 package를 사용해 보자. 두 가지 방법을 사용할 수 있다.

1. npx로 실행하기

$ npx ktmihs-bp react-webpack-ts new-react-app

직접 적용해보기

임시 test 폴더 안에서 적용해 보았다.

npx 명령어를 통해 설치한 후, vite app을 실행하면(scripts에 설정한 명령어로 실행. 이 경우엔 npm run dev),

dev 명령어로 vite 앱 실행하기

테스트 페이지를 확인할 수 있다.

boilerplate에 설정해둔 옹졸한 index page

 

2. npm으로 실행하기

또한 npm에 publish 했기 때문에 npm 명령어로도 해당 package를 설치하고 실행할 수 있다. 

$ npm i ktmihs-bp
$ ktmihs-bp react-webpack-ts new-react-app

 

 

이제 등록해둔 boilerplate를 사용하여 프로젝트 진행 시, 내가 발행한 package를 사용해 간편하게 기본 세팅을 할 수 있다.

 

 

https://docs.npmjs.com/updating-your-published-package-version-number

Updating your published package version number | npm Docs

https://heropy.blog/2019/01/31/node-js-npm-module-publish/

내 NPM 패키지(모듈) 배포하기

https://velog.io/@jjunyjjuny/React-TS-boilerplate-%EC%A0%9C%EC%9E%91%EA%B8%B0-%EB%B0%B0%ED%8F%AC-%EB%B0%8F-npx

React + TS boilerplate 제작기 2 - 설치 패키지 & npx

https://docs.npmjs.com/about-package-readme-files

About package README files | npm Docs