npmへの公開とセマンティックバージョニング

公開する前に、必ず npm publish --dry-run を実行してください。これは実際には何もアップロードせずに公開をシミュレートし、含まれるファイル、そのサイズ、パッケージの tarball の内容を正確に表示します。ソースファイルを誤って含めてしまったり、dist ディレクトリが不足していたりするなど、よくある間違いを見つけられます。

package.json の files フィールドを使って、公開されるファイルを制御します。"files": ["dist", "README.md"] のように指定します。このホワイトリスト方式は、ブラックリスト方式の .npmignore より安全です。.npmignore では、追加し忘れた機密ファイルが漏えいする可能性があるためです。dist、型宣言、ドキュメントは必ず含めてください。src、テスト、node_modules は決して含めないでください。

npm パッケージでは、セマンティックバージョニング（semver）に従います。形式は MAJOR.MINOR.PATCH です。互換性を壊す変更（props の削除や API シグネチャの変更）には MAJOR を上げます。後方互換性のある新機能（新しいコンポーネントや新しいオプションの props）には MINOR を上げます。後方互換性のあるバグ修正には PATCH を上げます。0.x.x は安定版になる前の段階と見なされるため、どのような変更でも互換性が壊れる可能性があります。

プレリリース識別子は、そのバージョンがまだ本番利用の準備ができていないことを示します。初期の実験的なビルドには 1.0.0-alpha.1、機能は完成しているもののバグが残っている可能性があるバージョンには 1.0.0-beta.2、最終テストの準備ができたリリース候補には 1.0.0-rc.1 を使います。プレリリースは npm publish --tag beta で公開し、デフォルトでインストールされないようにしてください。

Changesets は、コンポーネントライブラリでパッケージのバージョンと変更履歴を管理するための標準ツールです。ワークフローでは、コントリビューターが yarn changeset add を実行して、変更内容と変更種別（major/minor/patch）を記録します。CI では yarn changeset version を実行してパッケージのバージョンを更新します。公開時には yarn changeset publish を実行して npm にプッシュします。

Changesets は、コントリビューターがコミットした changeset ファイルに基づいて、CHANGELOG.md を自動的に生成および管理します。各エントリには、バージョン番号、リリース日、変更内容の説明が含まれます。これにより、手作業で CHANGELOG を管理しなくても、すべてのバージョンの履歴を人が読みやすい形で残せます。

semantic-release は、conventional commit メッセージから次のバージョンを判断する、完全自動化されたバージョニングツールです（feat: → minor、fix: → patch、BREAKING CHANGE: → major）。バージョンを更新し、変更履歴を生成して npm に公開するまでのすべてを、main へのマージをきっかけに CI で実行します。手動でのバージョン管理は必要ありません。

スコープなしパッケージ（my-component）は常に公開されます。スコープ付きパッケージ（@myorg/my-component）はデフォルトで制限付き（非公開）です。公開するには npm publish --access public を実行してください。制限付きパッケージには、npm の有料アカウントまたは組織が必要です。初めて公開する前に、アクセス設定を確認してください。

npm provenance は、公開したパッケージを特定の git コミットに検証可能な形で関連付けます。GitHub Actions で npm publish --provenance を実行して有効にしてください。利用者は、インストールしたパッケージが npm レジストリのページに表示された正確なソースコミットからビルドされたものかどうかを検証できます。これにより、ソフトウェアサプライチェーンのセキュリティが大幅に向上します。

あるバージョンに重大なバグや互換性を壊す変更がある場合は、非推奨にしてください。npm deprecate your-package@1.2.3 "Security vulnerability, upgrade to 1.2.4" のように実行します。npm は、そのバージョンをインストールしようとする利用者に非推奨警告を表示します。これはバージョンを削除するものではありません（npm はデフォルトで公開済みのバージョンを削除しません）が、利用者にアップグレードを促します。

スコープ付きパッケージは、@scope/package-name という形式を使用します。スコープには通常、npm のユーザー名または組織名を指定します。スコープ付きパッケージを使うと、誰がパッケージを保守しているかが明確になり、スコープなしパッケージとの名前の衝突も防げます。非公開パッケージや、組織に関連付けたオープンソースパッケージには、スコープ付きパッケージを使用してください。

セマンティックバージョニングでは、MAJOR のバージョン番号を上げるのはどのような場合ですか。

公開前の確認には npm publish --dry-run を使用し、公開するファイルの制御には files フィールドを使用します。セマンティックバージョニングでは、互換性を壊す変更に MAJOR、新機能に MINOR、修正に PATCH を使用します。プレリリースには -alpha/-beta/-rc タグを使用します。Changesets は、共同開発するライブラリのバージョニングと CHANGELOG 生成を自動化します。semantic-release は conventional commit からの処理を自動化します。サプライチェーンのセキュリティのために --provenance を有効にします。バグのあるバージョンは npm deprecate で非推奨にします。