npm-library-setup

ESM を使用した npm ライブラリのセットアップ

このスキルでは、ES Modules（ESM）を優先して、package.json を使用した npm ライブラリのセットアップ方法を包括的に説明します。

概要

このスキルでは、次のような npm パッケージを作成できます。

• "type": "module" を使用して ES Modules（ESM）を利用する
• 最新の exports フィールドを設定する（非推奨の module フィールドは使用しない）
• ゼロ設定でバンドルできる bunchee を使用する
• 最新のテストに vitest を使用する
• TypeScript と React コンポーネントライブラリをサポートする

このスキルを使用するタイミング

次の場合に使用します：

• 「npm パッケージをセットアップする」
• 「新しい npm ライブラリを作成する」
• 「ESM 用に package.json を設定する」
• 「TypeScript の npm パッケージをセットアップする」
• 「React コンポーネントライブラリを作成する」

対象カテゴリ：

• ESM を使用した基本的なパッケージのセットアップ
• TypeScript パッケージの設定
• React コンポーネントライブラリのセットアップ
• bunchee を使用したビルド設定
• vitest を使用したテストのセットアップ

クイックスタート

1. パッケージを初期化します。

   npm init -y
   

2. package.json に "type": "module" を追加して ESM 用に設定します。

3. ビルドツールとテストツールをインストールします。

   npm install -D bunchee vitest
   

4. src/ にソースファイルを作成し、npm run build を実行します。

基本的な設定

package.json

{
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "bunchee",
    "test": "vitest",
    "test:run": "vitest run"
  },
  "engines": {
    "node": ">=20"
  }
}

注： 現在メンテナンスされている LTS バージョンのうち、最も古いものを使用してください（Node.js リリーススケジュールを確認してください）。

主な原則

1. ESM 優先： 純粋な ESM パッケージでは "type": "module" を使用します
2. 最新の exports： 非推奨の module フィールドではなく、exports フィールドを使用します
3. ゼロ設定のバンドル： Bunchee がほとんどの設定を自動的に処理します
4. ファイル拡張子： インポートでは明示的な .js 拡張子を使用します（TypeScript 内でも同様です）
5. ケバブケースのファイル名： ファイルパスにはケバブケースを使用します

TypeScript のセットアップ

TypeScript をインストールして設定します。

npm install -D typescript @types/node

tsconfig.json を作成します。

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "NodeNext",
    "declaration": true,
    "strict": true
  }
}

Bunchee は TypeScript を自動的にコンパイルし、.d.ts ファイルを生成します。

React コンポーネントライブラリ

React を開発用依存関係としてインストールします。

npm install -D react @types/react

peerDependencies を設定します。

{
  "peerDependencies": {
    "react": "*"
  }
}

ベストプラクティス

1. ✅ exports フィールドを使用する（非推奨の module フィールドは使用しない）
2. ✅ インポートでは明示的なファイル拡張子（.js）を使用する
3. ✅ ファイルパスにはケバブケースを使用する
4. ✅ 実行時依存関係と開発用依存関係を分ける
5. ✅ メンテナンスされている最も古い LTS バージョンを Node.js のバージョンとして指定する
6. ✅ ソースコードは ESM 構文で記述する

よくあるパターン

ESM のインポート／エクスポート

// Named exports
export function greet(name) {
  return "Hello, " + name + "!";
}

// Default export
export default class MyLibrary {}

// Import
import { greet } from './module.js';
import MyLibrary from './MyLibrary.js';

重要： TypeScript ファイルでも、インポートには必ず .js 拡張子を使用してください。

ファイル構成

my-package/
├── package.json
├── src/
│   ├── index.js         # or index.ts
│   └── helpers.js
├── dist/                # Build output
└── README.md

参考資料

詳しいガイドについては、references/ ディレクトリを参照してください。

• 入門ガイド
• Package.json の設定
• ESM の構文とパターン
• ビルドとテスト
• TypeScript パッケージ
• React パッケージ
• ベストプラクティス

例

動作する完全な例については、examples/ ディレクトリを参照してください。

• JavaScript ESM パッケージ
• TypeScript ESM パッケージ

追加リソース

• Node.js リリーススケジュール - メンテナンスされている最も古い LTS バージョンを確認します
• Bunchee ドキュメント - ビルドツール
• Vitest ドキュメント - テストランナー