첫 번째 NPM 패키지를 만드는 가장 쉬운 방법

이 가이드는 마이크로번들을 사용하여 처음부터 끝까지 NPM 패키지를 빌드하고 릴리스하는 가장 쉬운 프로세스를 안내합니다.

microbundle 에 대해 조금 이야기해 보겠습니다. 구성에 대해 걱정할 필요가 없고 패키지 개발에 집중할 수 있기 때문에 간단한 라이브러리에 특히 효과적이라고 생각합니다.

다음은 해당 기능의 간단한 목록입니다.

• 내장 구성; 여러분이 해야 할 일은 package.json 에 "내보내기" 필드를 추가하는 것뿐입니다.
• tsconfig.json 없이 즉시 TypeScript 지원
• 다양한 출력 형식(CJS, UMD, ESM)
• 내장형 Terser 압축

기본적으로 microbundle Rollup.js 위에 구축됩니다. 이 기사에서 언급한 것보다 빌드해야 할 라이브러리가 더 복잡하다면 순수 rollup.js 구성을 사용하는 것을 고려해 볼 수 있습니다.

패키지 초기화

예를 들어, 두 개의 숫자를 합산하는 간단한 라이브러리를 만들어 보겠습니다. 이 라이브러리는 sum 함수 하나만 내보냅니다.

1. 프로젝트에 대한 폴더를 생성하고 기본값으로 npm init 실행하여 package.json 생성합니다.

   
   

2. src 폴더에 index.ts 생성

    // src/index.ts export function sum(a: number, b: number) { return a + b; }

3. microbundle 설치

   npm i -D microbundle

   
   

4. package.json 다음 값으로 업데이트합니다.

    // package.json ... "type": "module", "source": "src/index.ts", // your source code "exports": { "types": "./dist/index.d.ts", // TypeScript declaration file "require": "./dist/index.cjs", // CommonJS entry point "default": "./dist/index.esm.js" // ES Module entry point }, "main": "./dist/index.cjs", // where to generate the CommonJS bundle "module": "./dist/index.esm.js", // where to generate the ESM bundle "unpkg": "./dist/index.umd.js", // where to generate the UMD bundle "types": "./dist/index.d.ts", // TypeScript declaration file for the package "scripts": { "build": "microbundle", // compiles "source" to "main", "module", "unpkg" "dev": "microbundle watch" // re-build when source files change } ...

5. 빌드 스크립트 실행

   npm run build

   
   

   출력에는 package.json 에 선언한 파일이 정확히 포함되어야 합니다.

   

그리고 짜잔, 우리는 첫 번째 패키지를 만들었습니다. 좀 더 복잡한 시나리오를 살펴보겠습니다.

라이브러리에 React 추가하기

React를 라이브러리로 가져오려면 여전히 microbundle 사용할 수 있지만 이제 빌드 명령은 다음과 같아야 합니다.

 microbundle --jsx React.createElement --jsxFragment React.Fragment --jsxImportSource react --globals react/jsx-runtime=jsx

향후 편의를 위해 build 스크립트에 package.json 에 대한 명령을 추가합니다.

 // package.json ... "scripts": { "build": "microbundle --jsx React.createElement --jsxFragment React.Fragment --jsxImportSource react --globals react/jsx-runtime=jsx" } ...

UI 구성 요소에 Storybook 사용

UI 라이브러리를 구축하는 동안 구성 요소를 개발, 시각화하고 문서용 데모 구성 요소를 제공할 수 있는 샌드박스가 필요할 수 있습니다.

여기 동화책 이 옵니다. 이는 구성 요소의 다양한 상태를 쉽게 설명할 수 있는 편리한 인터페이스와 번들러를 갖춘 샌드박스입니다. 구성 요소 상태의 각 캡처를 "스토리"라고 합니다.

해당 문서에서 가져온 이 사진은 다음과 같은 모습을 보여줍니다.

Storybook 설치는 매우 간단합니다. 라이브러리 내에서 명령을 실행하세요.

 npx storybook@latest init

이 명령은 Storybook에 필요한 모든 종속성을 설치하고, 실행할 스크립트를 추가하고, package.json 에 Storybook을 빌드하고, 기본 구성으로 .storybook 폴더를 만들고, src/stories 폴더에 스토리의 몇 가지 예를 추가합니다.

라이브러리 에 스타일 통합

CSS 파일 또는 CSS-in-JS의 두 가지 방법 중 하나로 스타일을 추가할 수 있습니다. CSS 파일을 사용하면 쉽게 사용자 정의할 수 있지만 별도로 포함해야 하는 반면, CSS-in-JS는 스타일을 단순화하지만 번들 크기를 늘립니다.

• CSS 파일

  src 디렉터리에 CSS 파일을 만들고 이를 루트 반응 구성 요소 파일로 가져옵니다.

   // src/index.tsx import './styles.css'; export const MySuperComponent = () => { return ( <h1 className="title">Hi there!</h1> ) };

  
  

  이제 빌드 명령을 다시 실행해 보겠습니다.

   npm run build

  
  

  가져온 styles.css 파일이 dist 폴더에 생성됩니다.

  

  엄청난! 필요한 스타일이 포함된 CSS 파일을 얻었습니다. 하지만 이 솔루션에는 약간의 불편함이 있습니다. CSS 파일은 패키지 설치 후 별도로 추가해야 합니다.

  
  

  따라서 라이브러리 사용자는 CSS 파일을 처리하기 위해 CSS 로더(예: 웹팩용 CSS 로더)를 사용해야 하며 사용법은 다음과 같습니다.

   import { MySuperComponent } from 'my-super-library'; import 'my-super-library/dist/styles.css'; export const App = () => { return ( <MySuperComponent /> ); }

  
  

• CSS-in-JS

  이 목적으로 스타일 구성 요소 와 같은 라이브러리를 사용할 수 있습니다. 그러면 다음과 같이 보일 것입니다:

   import styled from 'styled-components'; const Title = styled.h1` font-size: 30px; font-weight: bold; `; export const MySuperComponent = () => { return ( <Title>Hi there!</Title> ) };

  이 솔루션을 사용하면 사용자는 CSS 파일을 가져오고 프로젝트에 특수 로더를 추가할 필요가 없습니다. 라이브러리를 설치하면 구성 요소에 고유한 스타일이 적용됩니다. 그러나 이렇게 하면 번들 크기가 늘어나고 사용자가 CSS 선택기를 사용하여 요소를 맞춤설정하기가 더 어려워집니다.

가장 적합한 옵션을 선택하세요. 나는 CSS 파일을 사용하는 것을 선호하는데, 그 이유는 사용자가 CSS 선택기를 사용하여 모든 요소를 사용자 정의할 수 있고, 번들 크기에 영향을 주지 않으며, 더 빠르게 작동하기 때문입니다.

자세한 README.md 파일 개발

README.md 파일은 라이브러리에 대한 정보, 설치 방법, 기본 사용법 및 기능을 제공합니다. 이는 개발자가 리포지토리나 NPM 패키지를 접할 때 읽는 첫 번째 파일인 경우가 많으므로 간결하고 유익해야 합니다.

나는 다음 순서로 구조를 만들고 싶습니다.

1. 제목
2. 매우 짧은 패키지 설명
3. 멋진 통계 배지( shields.io )
4. 라이브러리가 UI 구성 요소인 경우 스크린샷을 포함하거나 CodeSandbox에 데모 링크를 제공하세요.
5. 기능 목록
6. 설치 설명서
7. 사용법이 포함된 코드 조각
8. 라이브러리에서 구성을 위해 허용하는 옵션 및 소품

영감을 얻으려면 dot-path-value 및 React-nested-dropdown 과 같은 내 패키지의 README.md 파일 예제를 참조할 수 있습니다.

종속성 관리 탐색

잘못하면 사용자가 버전 충돌이나 기타 문제에 직면할 수 있고 라이브러리를 제거해야 하기 때문에 이는 중요한 부분입니다. 이제 종속성 유형 간의 주요 차이점을 살펴보겠습니다.

• "devDependency"는 개발 전용이며 번들에 포함되지 않습니다. 예를 들어, 사용자가 사용할 필요가 없는 microbundle 패키지가 설치되어 있는 경우 이를 devDependency에 유지하면 번들에 표시되지 않습니다.

• "종속성"은 패키지와 함께 설치됩니다. 패키지가 사용자 프로젝트에서 작동하는 데 필요한 종속성을 포함합니다. "react"와 같은 일부 종속성은 사용자 프로젝트에 이미 설치되어 있을 수 있습니다. 패키지에 중복된 "반응"이 있으면 번들 크기가 늘어날 수 있습니다. 여기서는 "peerDependency"가 유용합니다.

• “peerDependency”는 패키지가 사용하지만 번들에 포함하지 않는 종속성입니다. 패키지는 사용자가 프로젝트에 가지고 있는 종속성 버전을 활용합니다.

  
  

  기본적으로 생태계를 위한 라이브러리를 생성하는 경우 피어 종속성을 지정해야 합니다. 예를 들어 React 구성 요소를 생성하는 경우 React를 피어 종속성으로 설정하세요. 달력을 사용하여 React 구성 요소를 개발하는 경우 React 및 날짜 계산 라이브러리(예: date-fns)를 PeerDependency로 추가하세요.

  
  

  사용자의 프로젝트에 지정된 피어 종속성이 없는 경우 npm install 명령은 경고를 표시하지만 종속성을 자동으로 설치하지는 않습니다.

어떻게 보이는지에 대한 작은 예입니다.

 // package.json ... "dependencies": { // libraries which will be installed along with your library "clsx": "^1.2.1" // just library for className combining }, "peerDependencies": { // user should have these packages installed "react": "^16.8.0 || ^17.0.0 || ^18.0.0" // user should have react 16.8+ version }, "devDependencies": { // won't be in user's bundle, these libraries just for your developing needs "@types/react": "^18.2.33", "react": "^18.2.0", // in case if we are using storybook, we need actual react library to render our components there "microbundle": "^0.15.1", }, ...

패키지에 GitHub 사용

NPM 패키지를 게시한다는 것은 공개적으로 액세스할 수 있다는 의미입니다(무료 계정이 있는 경우). 사용자로부터 피드백을 수집하려면 원본 코드에 대한 GitHub 리포지토리를 생성하면 됩니다. 사람들은 그곳에서 문제를 만들고 패키지에 관해 귀하와 소통할 수 있습니다. 또한 릴리스를 설명하고 별을 얻을 수도 있습니다!

이 단계를 건너뛸 수도 있지만 이는 개발자 문화의 필수적인 부분이며 오픈 소스에 귀중한 기여를 할 수 있습니다.

패키지 게시 및 유지 관리

패키지를 게시하기 전에 package.json 파일이 올바르게 구성되었는지 확인하는 것이 중요합니다. 따라야 할 몇 가지 중요한 단계는 다음과 같습니다.

1. 라이브러리의 핵심 기능에 대한 이름을 지정하고 설명하십시오. 예를 들어:

    "name": "react-color-picker"

   
   

2. GitHub 저장소 정보를 추가합니다(존재하는 경우).

    ... "homepage": "https://github.com/{your_repository}", "repository": { "type": "git", "url": "https://github.com/{your_repository}" }, "bugs": { "url": "https://github.com/{your_repository}/issues" }, ...

   
   

3. files 구성합니다.

    ... "files": [ "dist", ], ...

   라이브러리가 설치될 때 node_modules 에 포함될 파일을 지정해야 합니다. 일반적으로 dist 폴더를 포함하면 충분합니다.

   
   

4. keywords 추가:

   키워드는 패키지를 설명하고 NPM에서 검색 및 추천을 위해 사용하는 문자열 배열입니다. 사람들이 검색할 때 사용할 것으로 예상되는 패키지 관련 단어를 선택하세요. sum 라이브러리에 대한 키워드를 만들어 보겠습니다.

    ... "keywords": ["typescript", "math", "sum", "numbers", "arithmetic", "calculator", "calculation"] ...

   사용자는 종종 "수학용 타이프스크립트 라이브러리" 또는 "반응 달력 선택기"와 같은 용어를 검색하므로 기술을 지정하는 것이 중요합니다.

   
   

5. 아직 NPM 계정이 없다면 계정을 만들고 터미널에서 npm login 실행하세요. 메시지에 따라 계정을 인증하세요. 기본적으로 패키지 버전은 1.0.0 입니다. package.json 파일에서 확인할 수 있습니다. 0.0.1 로 변경하는 것이 좋습니다.

   
   

6. npm publish 실행하면 완료됩니다! 나중에 버전을 업데이트하려면 npm version patch 명령을 사용하여 버전을 올린 다음 npm publish 사용하여 업데이트된 패키지를 게시하세요.

결론

보시다시피, 자신만의 라이브러리를 만드는 것은 매우 쉽습니다! 기본적으로 이것이 패키지를 생성하고 유지 관리하는 데 필요한 전부입니다. microbundle 로 라이브러리를 제한하는 데 어려움을 겪고 있다면 좀 더 구체적인 구성으로 Rollup.js를 사용하는 것이 좋습니다.

NPM 패키지를 만들고 오픈 소스에 기여하는 것은 모든 기술 수준의 개발자에게 보람 있고 귀중한 경험입니다. 이를 통해 코드를 커뮤니티와 공유하고, 많은 경험을 쌓고, 작업 포트폴리오를 구축할 수 있습니다.