---
title: エンジニア達の「完全に理解した」Talk　#76
tags:  #oss #npm #rxjs #web-serial #typescript  
author: [akihiko.KIgure](https://image.docswell.com/user/ic_lifewood)
site: [Docswell](https://www.docswell.com/)
thumbnail: https://bcdn.docswell.com/page/LJLMMKY9ER.jpg?width=480
description: npm パッケージ公開を完全に理解した
published: April 28, 26
canonical: https://image.docswell.com/s/ic_lifewood/KWRX2X-2026-04-28-182011
---
# Page. 1

![Page Image](https://bcdn.docswell.com/page/LJLMMKY9ER.jpg)

npm パッケージ公開を完全に理解した
エンジニア達の「完全に理解した」Talk
#76


# Page. 2

![Page Image](https://bcdn.docswell.com/page/47MYY2NV7W.jpg)

自己紹介
akihiko.KIgure a.k.a グレさん
渋谷とグンマー帝国の 2 拠点でフロントエンド開発をしています。
AI
QR
生
コ
ー
成
ド
コ
ンテンツは誤り
を含む可能性があり
ます。


# Page. 3

![Page Image](https://bcdn.docswell.com/page/P7R99MDWE9.jpg)

個人的推しOSS
※アルファベット順
Angular
CHIRIMEN Open Hardware
Firebase


# Page. 4

![Page Image](https://bcdn.docswell.com/page/PJXQQV1V7X.jpg)

個人的推しOSS
※アルファベット順
Google Cloud
MDN Web Docs
Nx
Rust


# Page. 5

![Page Image](https://bcdn.docswell.com/page/3JK99Q25JD.jpg)

今日テーマ
npm


# Page. 6

![Page Image](https://bcdn.docswell.com/page/LE3WWP41E5.jpg)

今日お話する事
● npm公開でやった事
● 再現できる手順
● 失敗ポイント


# Page. 7

![Page Image](https://bcdn.docswell.com/page/8EDKKLQK7G.jpg)

題材：@gurezo/web-serial-rxjs
AI
生イ
ア
成
コ
コ
ン
ンテンツは誤り
を含む可能性があり
ます。
AI
QR
生
コ
ー
成
ド
コ
ンテンツは誤り
を含む可能性があり
ます。


# Page. 8

![Page Image](https://bcdn.docswell.com/page/V7PKK2L3J8.jpg)

エンジニア達の「完全に理解した」Talk
#73
タイトル：Web Serial を完全に理解した
・Web Serial と RxJS を使ったライブラリ開発の LT です。
スライド
Youtube
connpass


# Page. 9

![Page Image](https://bcdn.docswell.com/page/2JVVVDQNJQ.jpg)

npm 公開とは？


# Page. 10

![Page Image](https://bcdn.docswell.com/page/5EGLLYW5JL.jpg)

配布システムを作る事


# Page. 11

![Page Image](https://bcdn.docswell.com/page/4JQYYM3L7P.jpg)

具体的に何をするの？


# Page. 12

![Page Image](https://bcdn.docswell.com/page/K74WWV15E1.jpg)

最初に作りたい物を創る！


# Page. 13

![Page Image](https://bcdn.docswell.com/page/LJ1YY3G2EG.jpg)

npm パッケージを使ったサンプル
npm パッケージのドキュメント
npm パッケージ本体


# Page. 14

![Page Image](https://bcdn.docswell.com/page/GJWGGPK272.jpg)

公開に向けて、やった事


# Page. 15

![Page Image](https://bcdn.docswell.com/page/4EZLLKZ473.jpg)

● npm パッケージ用 package.json の整備
● commit 規約の整備
● ISSUE_TEMPLATE の作成
● PULL_REQUEST_TEMPLATE の作成
● CONTRIBUTING の整備
● LICENSE の整備
● README の整備
● Document の整備
● CI / Release の整備


# Page. 16

![Page Image](https://bcdn.docswell.com/page/Y76WWQZG7V.jpg)

npm パッケージ用 package.json の整備
①
②
③
①
④
②
③


# Page. 17

![Page Image](https://bcdn.docswell.com/page/G75MMRWX74.jpg)

npm パッケージ
④


# Page. 18

![Page Image](https://bcdn.docswell.com/page/9J299DQQER.jpg)

npm パッケージ用 package.json の整備
⑤
⑥
⑦


# Page. 19

![Page Image](https://bcdn.docswell.com/page/DEY442WYJM.jpg)

npm パッケージのバージョニング（SemVer）
● バージョン形式
MAJOR.MINOR.PATCH（例：1.2.3）
● MAJOR：破壊的変更（互換性なし）
● MINOR：機能追加（互換性あり）
● PATCH：バグ修正（互換性あり）


# Page. 20

![Page Image](https://bcdn.docswell.com/page/VJNYY89R78.jpg)

例
● 1.0.0 → 2.0.0：API変更（breaking）
● 1.0.0 → 1.1.0：機能追加
● 1.0.0 → 1.0.1：バグ修正
ポイント
●利用者はバージョンで安全性を判断する
●間違えると利用者が壊れる


# Page. 21

![Page Image](https://bcdn.docswell.com/page/YE9PPK2ZJ3.jpg)

バージョンは“ユーザーとの契約”です


# Page. 22

![Page Image](https://bcdn.docswell.com/page/GE8DDRMYED.jpg)

実際のバージョニング歴


# Page. 23

![Page Image](https://bcdn.docswell.com/page/LELMMK397R.jpg)

commit 規約の整備
Conventional Commits に準拠した
コミットメッセージに矯正（強制）します


# Page. 24

![Page Image](https://bcdn.docswell.com/page/4JMYY2DVJW.jpg)

What is
Conventional Commits


# Page. 25

![Page Image](https://bcdn.docswell.com/page/PJR99M4W79.jpg)



# Page. 26

![Page Image](https://bcdn.docswell.com/page/PEXQQV2VJX.jpg)

@commitlint/cli
コミットメッセージが
規約（Conventional Commits）に
従っているかをチェックするCLIツール


# Page. 27

![Page Image](https://bcdn.docswell.com/page/3EK99QM5ED.jpg)

@commitlint/config-conventional
Conventional Commits に準拠した
ルールセットを提供する設定パッケージ


# Page. 28

![Page Image](https://bcdn.docswell.com/page/L73WWPY175.jpg)

husky
Gitのフック（pre-commit / commit-msg）を
設定して、コミット時に自動でチェックや
処理を実行するツール


# Page. 29

![Page Image](https://bcdn.docswell.com/page/87DKKL5KJG.jpg)

ISSUE_TEMPLATE の作成
目的：ルールに沿って、Issue を作成する為
テンプレート種類
● 機能改善（英語版含む）
● バグ報告（英語版含む）
● 質問 / Q&A （英語版含む）
● README / ドキュメント（英語版含む）


# Page. 30

![Page Image](https://bcdn.docswell.com/page/VJPKK2G3E8.jpg)

※海外の方が使う事も想定して、英語版も作成しました


# Page. 31

![Page Image](https://bcdn.docswell.com/page/2EVVVD6NEQ.jpg)

PULL_REQUEST_TEMPLATE の作成
目的：ルールに沿って、PR を作成する為


# Page. 32

![Page Image](https://bcdn.docswell.com/page/57GLLYN5EL.jpg)

CONTRIBUTING の整備
目的：
開発ルールや手順を明文化し誰でも同じ品質で
貢献出来る様にする為


# Page. 33

![Page Image](https://bcdn.docswell.com/page/4EQYYMQLJP.jpg)

LICENSE の整備
目的：
利用・改変・再配布の
条件を明確にし
利用者と開発者双方の
法的リスクを防ぐ為


# Page. 34

![Page Image](https://bcdn.docswell.com/page/KJ4WWVN571.jpg)

README の整備
目的
ライブラリの概要・使い方・導入手順を明確に
し、利用者が迷わず使い始められる様にする為


# Page. 35

![Page Image](https://bcdn.docswell.com/page/LE1YY3527G.jpg)

Document の整備
目的：
API仕様や使い方を体系的に提供し
利用者が正しく効率的に活用出来る様にする為


# Page. 36

![Page Image](https://bcdn.docswell.com/page/GEWGGP52J2.jpg)

typedoc
TypeScriptのコードからAPIドキュメントを自
動生成するドキュメントツール


# Page. 37

![Page Image](https://bcdn.docswell.com/page/47ZLLKN4J3.jpg)

typedoc-rhineai-theme
TypeDocの出力を見やすくカスタマイズするた
めのテーマ（デザインテンプレート）


# Page. 38

![Page Image](https://bcdn.docswell.com/page/YJ6WWQ8GJV.jpg)

CI / Release の整備
目的：
品質を担保しつつビルド・テスト・公開を
自動化し、安定して再現性のあるリリースを行
う為


# Page. 39

![Page Image](https://bcdn.docswell.com/page/GJ5MMR9XJ4.jpg)



# Page. 40

![Page Image](https://bcdn.docswell.com/page/LE3WWPY4E5.jpg)

ci.yml
● CI setup
● パッケージインストール
● lint
● build
● test


# Page. 41

![Page Image](https://bcdn.docswell.com/page/8EDKKL557G.jpg)

commitlint.yml
husky と併用して、 Conventional Commits
に準拠したコミットメッセージを確認する


# Page. 42

![Page Image](https://bcdn.docswell.com/page/V7PKK2GDJ8.jpg)

deploy-docs.yml
typedoc で、生成されたドキュメントを
git pages にデプロイします。


# Page. 43

![Page Image](https://bcdn.docswell.com/page/2JVVVD6GJQ.jpg)

npm パッケージ公開用の tag
$ git tag <バージョン>
$ git push origin <バージョン>
=> release.yml のトリガー


# Page. 44

![Page Image](https://bcdn.docswell.com/page/5EGLLY2DJL.jpg)

release.yml 実行例
● `v*` タグ push を起点に、テスト・ビルド・公開までを自動
実行する release ワークフロー
● `npm pack --dry-run` で README 同梱を事前検証し、壊れ
た成果物の公開を防止
● Trusted Publishing（OIDC）で npm に公開し、同時に
GitHub Release も自動作成


# Page. 45

![Page Image](https://bcdn.docswell.com/page/4JQYYMPX7P.jpg)

Trusted Publishing（OIDC）
● CI が「正しい実行元であること」を証明して
トークン無しで安全に npm publish できる仕組み


# Page. 46

![Page Image](https://bcdn.docswell.com/page/K74WWVY2E1.jpg)

つまりどういう事
だってばよ？（なると風


# Page. 47

![Page Image](https://bcdn.docswell.com/page/LJ1YY36KEG.jpg)

従来（トークン方式）
GitHub → 「パスワード（NPM_TOKEN）」を持ってる →
npm にログイン
問題
パスワードを保存する必要がある
パスワードが漏れたら終わり


# Page. 48

![Page Image](https://bcdn.docswell.com/page/GJWGGPWP72.jpg)

OIDC（Trusted Publishing）
GitHub
→ 「私はこのリポジトリです」と証明
→ npm が信頼して OK 出す
ポイント
パスワード不要
その場限りの証明


# Page. 49

![Page Image](https://bcdn.docswell.com/page/4EZLLK5673.jpg)

もう少しだけ正確に


# Page. 50

![Page Image](https://bcdn.docswell.com/page/Y76WWQ9L7V.jpg)

● GitHub Actions が「身分証明（OIDCトークン）」を発行
● npm に「このワークフローから実行してます」と証明
● npm が確認して publish を許可
しかも
トークンは使い捨て（短時間で無効）
保存不要


# Page. 51

![Page Image](https://bcdn.docswell.com/page/G75MMRNM74.jpg)

失 敗 談


# Page. 52

![Page Image](https://bcdn.docswell.com/page/9J299D5RER.jpg)

● dist が入らない
=> build 忘れ / files の設定不備
● README が表示されない
=> README が tarball に無い
● LICENSE / note 問題
=> 権利情報や release 情報が崩れている
=> 公開物として不完全


# Page. 53

![Page Image](https://bcdn.docswell.com/page/DEY442K5JM.jpg)

What is tarball


# Page. 54

![Page Image](https://bcdn.docswell.com/page/VJNYY8R478.jpg)

npm に公開されるパッケージの中身を
まとめた圧縮ファイル（.tgz）の事


# Page. 55

![Page Image](https://bcdn.docswell.com/page/YE9PPKM4J3.jpg)

npm パッケージ公開チェックリスト
● 設計・配布物
● 自動化・セキュリティ
● 運用ドキュメント


# Page. 56

![Page Image](https://bcdn.docswell.com/page/GE8DDRLVED.jpg)

● 設計・配布物
□ files / exports / types を言語化できる
□ dist / README / LICENSE を tarball に入れる
□ prepublishOnly で build を強制する


# Page. 57

![Page Image](https://bcdn.docswell.com/page/LELMMKLR7R.jpg)

● 自動化・セキュリティ
□ PR CI で lint / build / test を前倒し
□ tag release を workflow に切り出す
□ OIDC / provenance の目的を説明できる


# Page. 58

![Page Image](https://bcdn.docswell.com/page/4JMYY2MPJW.jpg)

● 運用ドキュメント
□ CONTRIBUTING / ISSUE / PR template がある
□ RELEASING がある
□ docs が公開後の利用導線になっている
□ ドキュメントに英語版がある（世界公開なら必須）


# Page. 59

![Page Image](https://bcdn.docswell.com/page/PJR99MVY79.jpg)

npm publish は単なる1コマンドではなく
「いつでも同じ品質で公開できる仕組み」を作る事


# Page. 60

![Page Image](https://bcdn.docswell.com/page/PEXQQVZ4JX.jpg)

お ま け


# Page. 61

![Page Image](https://bcdn.docswell.com/page/3EK99Q8PED.jpg)

npm パッケージ
公開サイト


# Page. 62

![Page Image](https://bcdn.docswell.com/page/L73WWP2475.jpg)

https://www.npmjs.com/
https://www.npmjs.com/
https://npmx.dev/
https://npmx.dev/


# Page. 63

![Page Image](https://bcdn.docswell.com/page/87DKKLZ5JG.jpg)

ライブラリ公開後の
累計ダウンロード数


# Page. 64

![Page Image](https://bcdn.docswell.com/page/VJPKK2DDE8.jpg)



# Page. 65

![Page Image](https://bcdn.docswell.com/page/2EVVVD1GEQ.jpg)



# Page. 66

![Page Image](https://bcdn.docswell.com/page/57GLLY8DEL.jpg)

サプライチェーン攻撃


# Page. 67

![Page Image](https://bcdn.docswell.com/page/4EQYYM9XJP.jpg)

OSSは依存関係を通じて攻撃されることがある
影響
- 自分のコードは安全でも影響を受ける
- 利用者全体に広がる
対策
- バージョン管理（SemVer）
- CI での検証
- 信頼できるリリースプロセス


# Page. 68

![Page Image](https://bcdn.docswell.com/page/KJ4WWVX271.jpg)

だからこそ・・・


# Page. 69

![Page Image](https://bcdn.docswell.com/page/LE1YY3NK7G.jpg)

● バージョンをちゃんと上げる
● CI で検証する
● release をコントロールする


# Page. 70

![Page Image](https://bcdn.docswell.com/page/GEWGGP4PJ2.jpg)

実施した対策


# Page. 71

![Page Image](https://bcdn.docswell.com/page/47ZLLK26J3.jpg)



# Page. 72

![Page Image](https://bcdn.docswell.com/page/YJ6WWQVLJV.jpg)



# Page. 73

![Page Image](https://bcdn.docswell.com/page/GJ5MMRDMJ4.jpg)

これが出来たら・・・


# Page. 74

![Page Image](https://bcdn.docswell.com/page/9E299D8R7R.jpg)

皆で npm パッケージを
公開しよう


# Page. 75

![Page Image](https://bcdn.docswell.com/page/D7Y44265EM.jpg)

そして・・・


# Page. 76

![Page Image](https://bcdn.docswell.com/page/VENYY8Z4J8.jpg)

ドヤろう（提案


# Page. 77

![Page Image](https://bcdn.docswell.com/page/Y79PPKZ4E3.jpg)

まとめ
npm パッケージ公開 できるよ
にんげんだもの
ぐれを


# Page. 78

![Page Image](https://bcdn.docswell.com/page/G78DDR1V7D.jpg)

ご静聴ありがとうございました！