初めての NPM パッケージを作成する最も簡単な方法

このガイドでは、マイクロバンドルを使用して、NPM パッケージを構築してリリースする最も簡単なプロセスを最初から最後まで説明します。

microbundleについて少し話しましょう。構成について心配する必要がなく、パッケージの開発に集中できるため、単純なライブラリの場合に特に効果的だと思います。

以下にその機能の短いリストを示します。

• 組み込みの構成。 package.jsonに「exports」フィールドを追加するだけです。
• tsconfig.jsonなしですぐに使える TypeScript サポート
• 複数の出力形式 (CJS、UMD、ESM)
• 組み込みの Terser 圧縮

基本的に、 microbundle rollup.jsの上に構築されます。この記事で説明するよりも複雑なライブラリを構築する必要がある場合は、純粋なrollup.js構成の使用を検討してください。

パッケージの初期化

例として、2 つの数値を合計するための単純なライブラリを作成してみましょう。このライブラリは、関数sumを 1 つだけエクスポートします。

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

将来の便宜のために、 package.jsonへのコマンドをbuildスクリプトに追加します。

 // 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 に必要な依存関係をすべてインストールし、実行するスクリプトを追加して、Storybook をpackage.jsonにビルドし、デフォルト構成でフォルダー.storybookを作成し、ストーリーのいくつかの例をフォルダーsrc/storiesに追加します。

スタイルをライブラリに統合する

CSS ファイルまたは CSS-in-JS の 2 つの方法のいずれかでスタイルを追加できます。 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 ローダー (Webpack の CSS ローダーなど) を使用して CSS ファイルを処理する必要があり、その使用法は次のようになります。

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

  
  

• JS 内の CSS

  この目的のために、スタイル付きコンポーネントのようなライブラリを使用できます。そして、それは次のようになります:

   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やreverse-nested-dropdown など、私のパッケージのREADME.mdファイルの例を参照してください。

依存関係管理のナビゲート

これは重要な部分です。間違ったやり方をすると、ユーザーがバージョンの競合やその他の問題に直面し、ライブラリを削除しなければならなくなる可能性があります。そこで、依存関係の種類の主な違いを見てみましょう。

• 「devDependency」は開発専用であり、バンドルには含まれません。たとえば、ユーザーが使用する必要のないmicrobundleパッケージがインストールされている場合、それを devDependency に保持しておくと、バンドルには表示されません。

• 「依存関係」はパッケージとともにインストールされます。パッケージがユーザーのプロジェクトで動作するために必要な依存関係を含めます。 「react」などの一部の依存関係は、ユーザーのプロジェクトにすでにインストールされている可能性があることに注意してください。パッケージ内に重複した「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"] ...

   ユーザーは「数学用の typescript ライブラリ」や「react カレンダー ピッカー」などの用語を検索することが多いため、テクノロジを指定することが重要です。

   
   

5. NPMアカウントをまだ作成していない場合は作成し、ターミナルでnpm loginを実行します。プロンプトに従ってアカウントを認証します。デフォルトでは、パッケージのバージョンは1.0.0です。 package.jsonファイルで確認できます。 0.0.1に変更することをお勧めします。

   
   

6. npm publishすれば完了です。今後バージョンを更新するには、コマンドnpm version patch使用してバージョンをインクリメントし、更新されたパッケージをnpm publishで公開します。

結論

ご覧のとおり、独自のライブラリを作成するのは非常に簡単です。基本的に、パッケージの作成と保守に必要なのはこれだけです。 microbundleを使用してライブラリを制限するのに苦労している場合は、より具体的な構成でrollup.jsを使用することをお勧めします。

NPM パッケージを作成し、オープンソースに貢献することは、あらゆるスキル レベルの開発者にとって、やりがいのある貴重な経験です。これにより、コードをコミュニティと共有し、多くの経験を積み、自分の作品のポートフォリオを構築することができます。