npm publish は取り消せません。CLIツールを作り、公開する前に確認することを全部確かめます。
この回は、実際に世界に向けて公開します。そして、その操作は取り消せません。 公開まで進むかどうかは、⑥まで読んでから決めてください。⑨に「公開しない」やり方をまとめてあります。どちらも同じ重さの選択です。
作業場所は VMの中(Ubuntu Server)です。ただしブラウザの操作だけは、ホストのWindowsから行います(VMにはブラウザが入っていないため)。
あなたはこの1年、npm install を何百回も打ってきました。
npmの回で node_modules の中を覗き、パッケージマネージャの回で pnpm と Bun を測り、ビルドツールの回で Vite を入れました。全部、取ってくる側です。
その一方で、こういうことをしていませんでしたか。
~/bin/toc.sh
~/bin/check.sh
~/scripts/backup.sh
シェルスクリプトの回で「3回打ったコマンドはスクリプトにする」と書きました。実際、スクリプトは増えたはずです。そして、そのスクリプトは、そのVMの中にしかありません。
- 別のマシンで使いたいときは、コピーします
- 直したら、コピーした先も直します
- 人に渡したいときは、
catして貼り付けます
レジストリの回で、まったく同じ話をしました。「そのイメージはVMの中にしかない」。今度はスクリプトです。
そして、あなたはもう答えを知っています。npm install -g で入るツールたちは、これを解決した状態のものです。
npm install -gの向こう側には、誰かがいます。 この回で、その側に行きます。
対象レベル: 中級 / 区分: 必修
この記事でわかること
- CLIツールの中身は、普通のスクリプトであること。ライブラリと違うのは
#!/usr/bin/env nodeの1行と、package.jsonのbinだけだということ process.argvの最初の2つは自分の引数ではないこと。知らないと必ず1個ずれる- 結果は標準出力、メッセージは標準エラーに出すという作法。これを守るとパイプで繋がり、破るとパイプが壊れる
- 終了コードを返さないツールは、CIから使えないこと。
0と0以外の意味 npm publishは取り消せないこと。同じ名前とバージョンは二度と使えず、消しても、入れてしまった人には影響が残る.gitignoreがあるから安全、ではないこと。.npmignoreを作った瞬間に.gitignoreは完全に無視される- 2要素認証をかけないアカウントの乗っ取りは、自分の被害では済まないこと。そのツールを入れた全員への攻撃になる
- 壊す変更を patch で出してはいけないこと。バージョン番号は感想ではなく約束だということ
- 公開しないという選択肢がいくつもあること。GitHubのURLから直接入れる /
npm packで渡す / スコープ付きで組織内に限る
この記事でやること
- 小さいCLIツールを1つ作る(Markdownの見出しを一覧にする
mdtoc)。npm linkで手元に入れて動かす process.argvの中身をそのまま表示させる。 そのうえで--helpと--versionを付ける- 標準入力から読めるようにして、
|で繋ぐ。 メッセージを標準エラーに追い出す - 終了コードを返す。 GitHub Actions から呼んで、赤くする
- 公開の直前に、取り返しのつかないことを確認する。 名前を調べ、
npm packで中身を見て、2要素認証をかける npm publishする。 そのあとnpm viewで、世界から見えていることを確かめる- バージョンを1つ上げる。 そしてやめ方(
deprecate)を先に知っておく
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| CLI(Command Line Interface) | コマンドとして打って使う形の道具。ls や git と同じ形 |
| シバン(shebang) | ファイルの1行目に書く #! で始まる行。「この中身を、どのプログラムに読ませるか」をOSに教える |
bin フィールド | package.json の項目。「このパッケージを入れたら、この名前のコマンドを生やす」という宣言 |
npm link | 手元のフォルダを、あたかも公開済みパッケージのように入れるコマンド。公開せずに試せる |
| 標準入力 / 標準出力 / 標準エラー | プログラムに最初から繋がっている3本の口。入る所・結果を出す所・文句を言う所 |
| 終了コード | プログラムが終わるときに残す数字。0 が成功、それ以外が失敗。人ではなく機械が読む |
| スコープ | パッケージ名の頭に付ける @名前/ の部分。名前の取り合いを避けられる |
| セマンティックバージョニング(semver) | 1.4.2 のような番号の付け方の決まり。数字のどこが動いたかで、壊れるかどうかが分かる |
deprecate | 「これはもう使わないでください」という札を貼ること。消すのではない |
| レジストリ | パッケージの置き場。npm の場合は npmjs.com。前にDockerで立てたものと同じ考え方 |
① 何を作るか — 小さくて、実際に自分が使うもの
題材を1つに決めます。 題材選びの回と同じで、ここで欲張ると終わりません。
作るのは、これです。
mdtoc— Markdownファイルを読んで、見出しの一覧(目次)を出す。
理由は3つあります。
- 自分が実際に使う。 このサイトの記事も、READMEも、Markdownです。見出しの一覧が欲しい場面は実際にありました
- 入力があって、出力がある。 だからパイプに繋がる形にできます。⑤でそこをやります
- 失敗する余地がある。 ファイルが無い、読めない、見出しが1つも無い。だから終了コードを返す意味があります
「1日で作れて、明日から使うもの」 が条件です。これより大きいものにしないでください。
もう1つの候補を書いておきます。
hitokotoのデータベースをバックアップするhitokoto-backupのような、自分専用の道具もCLI向きです。 ただし世界に公開する題材ではありません。(自分にしか使えないものを npm に出しても、名前を1つ潰すだけです。⑨に、そういうものの配り方を書きます)
② CLIの中身は、普通のスクリプトです
ここが、この記事でいちばん拍子抜けするところです。
CLIツールと、あなたがこれまで書いてきた node なんとか.js の間に、特別な仕組みはありません。 違うのは2つだけです。
| 普通のスクリプト | CLIツール | |
|---|---|---|
| 1行目 | 何も無い | #!/usr/bin/env node がある |
package.json | main がある | bin がある |
それだけです。順に見ます。
まず、置き場所を作る
VMの中で打ちます。
npm init -y で package.json ができます。中身はあとで全部書き直します。
中身を書く
まずは、いちばん短い形から始めます。 引数も何も見ません。
#!/usr/bin/env node
console.log('mdtoc が起動しました');
この3行が、もうCLIツールです。
1行目の #!/usr/bin/env node は何をしているか
シェルスクリプトの回で #!/bin/bash を書きました。あれと完全に同じ仕組みです。
シバンは、OSに向かって「このファイルの中身は、このプログラムに食わせてください」と言っています。
#!/bin/bash なら bash に、#!/usr/bin/env node なら node に渡されます。だから実行する人は、これが JavaScript で書かれていることを知らなくていいのです。
なぜ #!/usr/bin/node ではなく #!/usr/bin/env node なのか。 ここが実務で効きます。
あなたは Node.js を nvm で入れました。だから node の場所は、こういう所にあります。
/home/ubuntu/.nvm/versions/node/v22.11.0/bin/node
この場所は、人によって全部違います。 バージョンを切り替えれば、あなた自身の中でも変わります。ここを直接書いたら、他人の環境では動きません。
/usr/bin/env node は、「PATH の中から node という名前を探して、見つかったものを使え」という意味です。だから nvm でも、apt で入れた node でも、macOS でも動きます。
#!は、ファイルの1行目の、いちばん先頭でなければ効きません。 前に空行やコメントがあると、ただの文字列になります。
実行できるようにする
mdtoc が起動しました
node と打たずに動きました。 パーミッションの回でやった x が、ここで効いています。
bin フィールドを書く
いまはフルパスで打っています。どこからでも mdtoc と打てるようにします。
{
"name": "mdtoc",
"version": "0.1.0",
"description": "Markdownの見出しから目次を作る",
"type": "module",
"bin": {
"mdtoc": "./bin/mdtoc.js"
},
"engines": {
"node": ">=18"
},
"license": "MIT"
}
bin が「このパッケージを入れたら mdtoc というコマンドを生やす」という宣言です。
| 項目 | 意味 |
|---|---|
bin | 左が生やすコマンド名、右がその実体。名前とファイル名は違っていて構わない |
type: "module" | import を使う書き方(ESM)にする宣言。付けないと require の世界になる |
engines | どのNode.jsで動くか。古いNodeで入れようとすると警告が出る |
license | 前回やったもの。公開するなら必須。無いと npm publish が警告する |
npm link で、公開せずに手元へ入れる
ここが、この記事で最初に「おっ」となる所です。
added 1 package in 234ms
別のフォルダに移動して、打ちます。
mdtoc が起動しました
npm install -g で入れたツールと、まったく同じ形で動きました。 公開はしていません。
何が起きたのか。 npm link は、グローバルの bin 置き場にシンボリックリンク(実体への近道)を作ります。
/home/ubuntu/.nvm/versions/node/v22.11.0/bin/mdtoc
lrwxrwxrwx 1 ubuntu ubuntu 40 Sep 15 10:22 /home/ubuntu/.nvm/versions/node/v22.11.0/bin/mdtoc -> ../lib/node_modules/mdtoc/bin/mdtoc.js
リンクなので、~/mdtoc/bin/mdtoc.js を直せば、次に mdtoc と打った瞬間から反映されます。 入れ直しは要りません。
npm linkは、公開の代わりになります。 このあと最後まで作って、公開せずにnpm linkのまま使い続けるのは、まったく正しい選択です。⑨に書きます。
外すときは、これです。
③ 引数は process.argv に入っている — 最初の2つに注意
ここは、実際に表示させて確かめてください。 説明を読むより速いです。
#!/usr/bin/env node
console.log(process.argv);
打ちます。
[
'/home/ubuntu/.nvm/versions/node/v22.11.0/bin/node',
'/home/ubuntu/.nvm/versions/node/v22.11.0/lib/node_modules/mdtoc/bin/mdtoc.js',
'README.md',
'--depth',
'3'
]
自分が打った引数は、3つ目からです。
| 番号 | 中身 | 何か |
|---|---|---|
argv[0] | /home/.../bin/node | node 自身の場所 |
argv[1] | /home/.../mdtoc.js | 実行されたスクリプトの場所 |
argv[2] 以降 | README.md --depth 3 | ここが自分の引数 |
これを知らないと、必ず1個ずれます。 「引数が undefined になる」という詰まり方の、かなりの割合がこれです。
だから、最初にこう書きます。
const args = process.argv.slice(2);
slice(2) で頭の2つを捨てる。 これがCLIの定型句です。
--help と --version を必ず付ける
この2つが無いツールは、他人には使えません。 使い方を聞ける相手が、あなたしかいなくなるからです。
そして、あなた自身が半年後にその「他人」になります。
bin/mdtoc.js を、こう書き直します。
#!/usr/bin/env node
import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';
// package.json の version をそのまま使う(2か所に書かないため)
const here = dirname(fileURLToPath(import.meta.url));
const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
const HELP = `
mdtoc - Markdown の見出しから目次を作る
使い方:
mdtoc <ファイル> ファイルを読んで目次を出す
cat a.md | mdtoc 標準入力から読む
オプション:
-d, --depth <数> 何段目の見出しまで出すか (既定: 3)
-h, --help このヘルプを出す
-v, --version バージョンを出す
終了コード:
0 見出しが1つ以上見つかった
1 見つからなかった、または読めなかった
`.trim();
const args = process.argv.slice(2);
if (args.includes('-h') || args.includes('--help')) {
console.log(HELP);
process.exit(0);
}
if (args.includes('-v') || args.includes('--version')) {
console.log(pkg.version);
process.exit(0);
}
バージョンは package.json から読んでいます。 ここで console.log('0.1.0') と直接書くと、バージョンを上げたときに必ず食い違います。 番号は1か所にしか置きません。
確かめます。
0.1.0
--versionの出力は、バージョン番号だけにしてください。mdtoc version 0.1.0 :)のような飾りを付けると、他のスクリプトから数字として取り出せなくなります。
引数解析のライブラリ(commander、yargs など)は、まだ入れません。 いま必要なのは --help と --version と、ファイル名1つです。依存を増やすのは、手で書くのが辛くなってからです。
④ 標準出力と標準エラー — ここでシェルの回を回収します
本体を書きます。 そして、この節がこの記事のいちばん実用的なところです。
シェルスクリプトの回とテキスト処理の回で、grep や awk を | で繋ぎました。
なぜ
grepは|で繋がるのに、あなたのスクリプトは繋がらないのか。
答えは、出す場所を分けているかどうかです。
| 口 | 名前 | 何を出すか | パイプで次へ流れるか |
|---|---|---|---|
| 1番 | 標準出力(stdout) | 結果だけ | 流れる |
| 2番 | 標準エラー(stderr) | 人間へのメッセージ・エラー | 流れない(画面に出る) |
Node.js では、こうなります。
| 書き方 | 出る先 |
|---|---|
console.log() | 標準出力 |
console.error() | 標準エラー |
つまり、こういうことです。
console.log('読み込み中...'); // ⚠️ これをやると、目次に「読み込み中...」が混ざる
console.error('読み込み中...'); // ✅ 画面には出るが、パイプには流れない
進捗メッセージを
console.logで出した瞬間、そのツールはパイプで使えなくなります。mdtoc README.md > toc.mdとしたとき、toc.mdの先頭に「読み込み中…」が入るからです。
本体を書く
bin/mdtoc.js の、さきほどの続きに足します。
// --- 入力を読む -------------------------------------------------
async function readInput(file) {
if (file) {
return readFileSync(file, 'utf8');
}
// ファイル名が無いときは標準入力から読む
if (process.stdin.isTTY) {
console.error('mdtoc: ファイル名か、標準入力が必要です');
console.error(" 'mdtoc --help' を見てください");
process.exit(1);
}
const chunks = [];
for await (const chunk of process.stdin) chunks.push(chunk);
return Buffer.concat(chunks).toString('utf8');
}
// --- 見出しを拾う -----------------------------------------------
// バッククォート3つ以上、またはチルダ3つ以上で始まる行 = コードブロックの境目
const FENCE = /^\s*(?:`{3,}|~{3,})/;
const HEADING = /^(#{1,6})\s+(.*)$/;
function extractHeadings(text, maxDepth) {
const out = [];
let inFence = false;
for (const line of text.split('\n')) {
if (FENCE.test(line)) {
inFence = !inFence; // コードブロックの開始と終了で反転させる
continue;
}
if (inFence) continue; // ⚠️ コードブロックの中の # は見出しではない
const m = HEADING.exec(line);
if (!m) continue;
const level = m[1].length;
if (level > maxDepth) continue;
out.push({ level, text: m[2].trim() });
}
return out;
}
function toAnchor(text) {
return text
.toLowerCase()
.replace(/[^\p{L}\p{N}\s-]/gu, '') // 記号を落とす
.trim()
.replace(/\s+/g, '-');
}
inFence の判定を入れている理由は、⑦の「つまずいたところ」に書きます。入れないと、この記事自体が壊れます。
最後に、出力と終了コードです。
// --- 実行 -------------------------------------------------------
const files = args.filter((a) => !a.startsWith('-'));
const dIndex = args.findIndex((a) => a === '-d' || a === '--depth');
const maxDepth = dIndex >= 0 ? Number(args[dIndex + 1]) : 3;
if (!Number.isInteger(maxDepth) || maxDepth < 1 || maxDepth > 6) {
console.error(`mdtoc: --depth は 1〜6 の整数です (受け取った値: ${args[dIndex + 1]})`);
process.exit(1);
}
let text;
try {
text = await readInput(files[0]);
} catch (err) {
console.error(`mdtoc: 読めません: ${err.message}`);
process.exit(1);
}
const headings = extractHeadings(text, maxDepth);
if (headings.length === 0) {
console.error('mdtoc: 見出しが1つも見つかりませんでした');
process.exit(1);
}
const min = Math.min(...headings.map((h) => h.level));
for (const h of headings) {
const indent = ' '.repeat(h.level - min);
console.log(`${indent}- [${h.text}](#${toAnchor(h.text)})`);
}
-d の値の取り出しは、いちばん素朴なやり方にしてあります。ここを丁寧にやり始めると、引数解析ライブラリを書き始めることになります。 そうなったら、そのときに commander を入れてください。
動かす
そして、ここが本題です。パイプで繋ぎます。
grep や head と、同じように繋がりました。
メッセージが混ざらないことも確かめてください。
mdtoc: 読めません: ENOENT: no such file or directory, open '存在しないファイル.md'
エラーは画面に出て、out.txt は空のままです。 > は標準出力だけを拾うからです。これが「作法を守った」状態です。
[スクリーンショット: 01_パイプで繋ぐ.png] cat README.md | mdtoc と mdtoc README.md | head -5 を続けて実行し、両方が出力を返している画面を撮ってください。
⑤ 終了コードを返す — これでCIから使えるようになる
process.exit(1) を何度か書きました。この数字が何なのかを、はっきりさせます。
シェルスクリプトの回で exit 1 を書きました。あれと同じものです。
| 値 | 意味 |
|---|---|
0 | 成功。「言われたことができた」 |
0以外 | 失敗。慣習として 1 が汎用のエラー |
逆ではありません。 成功が 0 です。「エラーの数がゼロ」と考えると覚えられます。
確かめます。
0
1
なぜこれが重要なのか。
終了コードは、人ではなく機械が読みます。
mdtoc a.md && echo OK— 成功したときだけ次を実行する- GitHub Actions は、ステップの終了コードが
0以外ならジョブを失敗(赤)にします - ESLint や Prettier が CI を止められるのも、これだけが理由です
終了コードを返さないツールは、必ず成功したことになります。 どんなにエラーメッセージを出しても、CIは緑のまま通ります。
CIから呼んでみる
~/mdtoc/.github/workflows/ci.yml を作ります。
name: ci
on: [push]
jobs:
toc:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '22'
- run: node ./bin/mdtoc.js README.md
README.md に見出しが1つも無ければ、このジョブは赤くなります。 「READMEに見出しを書き忘れていないか」を機械が見張る、という使い方ができるようになりました。
これが、スクリプトを「配れる形にする」ことの実利です。 手元でしか動かないものは、CIには置けません。
⑥ 公開する前に — 取り返しのつかないことを確認する
ここが山場です。この節だけは、飛ばさずに読んでください。
いまから打つコマンドは、あなたが今まで打ったどのコマンドとも性質が違います。
npm publishは、取り消せません。
正確に書きます。
| 起きること | 説明 |
|---|---|
| 使ったバージョン番号は、二度と使えない | 0.1.0 を出したら、中身を差し替えて 0.1.0 を出し直すことは、削除後もできません |
| 名前を一度取ると、他人は使えない | そしてあなたも、消したあとすぐには取り戻せません |
| 消しても、入れた人の手元からは消えない | 誰かの package-lock.json に残り、その人のCIは、消えた瞬間に壊れます |
| 中身は全世界に公開される | 一度でも公開されたファイルは、ミラーやキャッシュに残ります。消したから見られない、ではありません |
Gitのように「commit を取り消す」ができません。 GitHubにpushした回や、前回 .env を履歴から消す話をしましたが、あれは自分のリポジトリだったからできたことです。npm は違います。
だから、publish の前にやることが4つあります。
6-1. 名前を調べる
取られていると、こう返ります。
mdtoc@1.1.0 | MIT | deps: none | versions: 5
Markdown table of contents generator
取られていないと、こうです。
npm error code E404
npm error 404 Not Found - GET https://registry.npmjs.org/mdtoc - Not found
E404 が「空いている」という意味です。 エラーに見えますが、ここでは良い知らせです。
[スクリーンショット: 02_npm_view_結果.png] npm view mdtoc を実行した結果を撮ってください。取られていた場合も、404 だった場合も、そのままで構いません。
短くて良い名前は、ほぼ全部取られています。 これは悪いことではありません。名前は有限の共有資源で、早い者勝ちにするしかないからです。
6-2. 取られていたら、スコープを付ける
似た名前をひねり出さないでください。 mdtoc2、mdtoc-cli、node-mdtoc。これは既存のパッケージと紛らわしく、間違えて入れる人が出ます。
正しい逃げ方は、スコープです。
@あなたのnpmユーザー名/mdtoc
スコープは、あなたのユーザー名(または組織名)の下に作られる名前空間です。 ここの中は、あなたしか使えません。名前の取り合いが、そもそも起きません。
package.json を直します。
{
"name": "@あなたのnpmユーザー名/mdtoc"
}
スコープ付きパッケージは、既定で「非公開」扱いになります。 そのまま
npm publishすると、有料プランでないと 402 で断られます。 公開したいときは、明示的にこう打ちます。npm publish --access publicこれは逆に言うと、
--access publicを付けない限り公開されないということです。 事故防止として、とても優秀な仕組みです。
6-3. npm pack で、何が入るかを目で見る
ここが、この記事でいちばん強く言いたいところです。
npm publishは、いまいるフォルダの中身を、あなたが思っているより多く持っていきます。
確かめる方法があります。公開せずに、公開されるものだけを作るコマンドです。
npm notice
npm notice package: mdtoc@0.1.0
npm notice === Tarball Contents ===
npm notice 1.2kB README.md
npm notice 421B package.json
npm notice 3.9kB bin/mdtoc.js
npm notice 1.1kB LICENSE
npm notice 87B .env
npm notice 12.4kB toc.md
npm notice === Tarball Details ===
npm notice total files: 6
.env が入っています。
これは作り話ではありません。.gitignore に .env を書いていても、こうなることがあります。 理由を書きます。
| 状況 | npm が見るもの |
|---|---|
.npmignore が 無い | .gitignore を代わりに使う → .env は除外される |
.npmignore が ある | .gitignore は完全に無視される → .npmignore に書いていないものは全部入る |
.npmignoreを作った瞬間に、.gitignoreの防御は全部消えます。 「両方が効く」ではなく「片方に切り替わる」です。ここを勘違いすると、除外していたつもりのものが出ます。
だから、除外を数える(.npmignore)のはやめて、入れるものを数える(files)ようにします。
{
"files": [
"bin/"
]
}
files に書いたものだけが入ります。 書き忘れたら入らないので、事故の向きが安全側です。(package.json / README / LICENSE は、書かなくても必ず入ります。逆に .git や node_modules は、書いても入りません)
もう一度確かめます。
npm notice === Tarball Contents ===
npm notice 1.2kB README.md
npm notice 465B package.json
npm notice 3.9kB bin/mdtoc.js
npm notice 1.1kB LICENSE
npm notice === Tarball Details ===
npm notice total files: 4
4つになりました。
実物を開いて確かめることもできます。
公開前チェックの3行
npm pack --dry-run git status grep -rn "パスワードやトークンらしき文字列" bin/シークレット管理の回でやったことと、狙いは同じです。出す前に、出るものを見る。
6-4. アカウントを作り、2要素認証をかける
まだアカウントを持っていないはずなので、ここから作ります。
ホストのWindowsのブラウザで npmjs.com を開き、Sign Up します。決めるのはユーザー名・メールアドレス・パスワードの3つです。
ユーザー名は、そのままスコープ名(
@ユーザー名/)になります。 あとから変えられないものとして選んでください。
アカウントができたら、すぐに2要素認証(2FA)を設定します。publish の前です。
npmjs.com の右上のアイコン → Account → Two-Factor Authentication から設定します。方式は2つあります。
| 方式 | 使うもの |
|---|---|
| 認証アプリ(TOTP) | スマートフォンの認証アプリ。QRコードを読ませて、6桁の数字を使う |
| セキュリティキー / パスキー | 物理キーや、端末に保存する鍵 |
そして、有効にする範囲を選びます。ここが大事です。
| 範囲 | かかる操作 |
|---|---|
| Authorization only | ログインのときだけ聞かれる |
| Authorization and writes | ログインに加えて、publish のときにも聞かれる |
「Authorization and writes」を選んでください。
なぜここまで言うのか。 あなたのアカウントが乗っ取られると、盗まれるのはあなたのものではありません。 攻撃者は、あなたの名前で新しいバージョンを publish できます。 そして、そのツールを入れている人全員が、次の
npm installでそれを実行します。これは実際に何度も起きてきた攻撃の形です。被害者はあなたではなく、あなたを信頼した人たちです。 レジストリの回で「依存を取ってくる先を、私たちは信頼している」と書きました。今度は、あなたが信頼される側になります。
[スクリーンショット: 03_2要素認証の設定.png] npmjs.com の Two-Factor Authentication の設定画面で、Authorization and writes が有効になっている状態を撮ってください。QRコードやリカバリコードが写らないようにしてください。
リカバリコード(復旧用のコード)は、必ず控えてください。 スマートフォンを失くしたときの唯一の入口です。
6-5. ログインする
VMの中で打ちます。
ここでVM特有の詰まりがあります。 いまの npm は、ブラウザを開いて認証させようとします。
npm notice Log in on https://www.npmjs.com/login
Login at:
https://www.npmjs.com/login?next=/login/cli/xxxxxxxx-xxxx-xxxx
Press ENTER to open in the browser...
VMにはブラウザが入っていません。 Enterを押しても何も起きません。
逃げ方は、表示されたURLをコピーして、ホストのWindowsのブラウザに貼ることです。 そこでログインすれば、VMの npm login が待つのをやめて先に進みます。
確認します。
あなたのユーザー名
6-6. publish する
ここまでの確認が全部済んでいることを、もう一度見てください。
- [ ]
npm view <名前>で、名前が空いている(または、スコープを付けた) - [ ]
npm pack --dry-runで、入るファイルを1つずつ目で見た - [ ]
.envや鍵や個人情報が入っていない - [ ]
package.jsonにlicense・description・repositoryがある - [ ] 2要素認証を「Authorization and writes」でかけた
- [ ]
npm whoamiが通る
そして、本番の前に、もう1回だけ空打ちできます。
--dry-run は何も送りません。 何が送られるかだけを見せます。
準備ができたら、これを打ちます。
2要素認証を「writes」にしていれば、6桁の数字を聞かれます。
This operation requires a one-time password.
Enter OTP: 123456
+ @あなたのユーザー名/mdtoc@0.1.0
公開されました。ここから先は、取り消せません。
6-7. 世界から見えていることを確かめる
そして、いちばん確実なのは、別の場所から入れてみることです。
npx は、入れずにその場で1回実行します。 npmの回でやったものです。これが動けば、他人の環境でも動きます。
ブラウザで https://www.npmjs.com/package/@あなたのユーザー名/mdtoc を開くと、READMEがそのままページになっています。 前回書いたREADMEが、ここで効きます。
[スクリーンショット: 04_npmjsの公開ページ.png] npmjs.com のパッケージページを開き、READMEが表示されている画面を撮ってください。
⑦ バージョンの付け方 — 番号は感想ではなく約束です
公開した瞬間に、新しい責任が1つ生まれました。
誰かの
package.jsonに"mdtoc": "^0.1.0"と書かれるかもしれない。
^ が付いていると、その人は次の npm install で、あなたが出した新しいバージョンを自動で受け取ります。 中身を見ずにです。
だから、番号の付け方に決まりがあります。セマンティックバージョニング(semver)です。
1 . 4 . 2
│ │ └── パッチ
│ └────── マイナー
└────────── メジャー
| 上げる場所 | 意味 | 例 |
|---|---|---|
パッチ(1.4.2 → 1.4.3) | バグを直した。使い方は変わらない | コードブロックの中の # を拾っていたのを直した |
マイナー(1.4.2 → 1.5.0) | 機能を足した。今までの使い方は壊れない | --json オプションを足した |
メジャー(1.4.2 → 2.0.0) | 今までの使い方が壊れる | --depth の既定値を 3 から 2 に変えた |
いちばんやってはいけないのは、壊す変更をパッチで出すことです。
^1.4.2と書いた人は、「1.x.x の間は壊れない」という約束を信じています。 そこにパッチのつもりで壊す変更を入れると、その人は、何も変えていないのに、朝CIが赤くなります。 そして原因を探すのに半日使います。
「これは壊す変更か?」の判断は、こう考えると分かります。
既存の使い方のうち、1つでも動かなくなるものがあるか。
オプション名を変えた、既定値を変えた、出力の形を変えた、終了コードの意味を変えた。全部メジャーです。 「小さい変更だから」は関係ありません。大きさではなく、壊れるかどうかです。
0.x.x の間だけは違う
0. で始まっている間は、「まだ約束していない」という意味です。 semver では 0.x は不安定版として扱われ、マイナーを上げても壊してよいことになっています。
だから、最初は 0.1.0 から始めてください。 固まってから 1.0.0 にします。1.0.0 を出すというのは、「ここから約束します」という宣言です。
npm version を使う
package.json を手で書き換えないでください。
v0.1.1
これが1コマンドで3つやります。
package.jsonのversionを書き換える- その変更をコミットする
v0.1.1というGitのタグを打つ
作業中の変更が残っていると、npm version は動きません。 先にコミットしてください。これは意地悪ではなく、「どのコードがどのバージョンか」を確実にするためです。
タグも一緒に送ります。
npm publishを打つ前に、必ずnpm pack --dry-runをもう一度。ファイルは増えているかもしれません。
⑧ やめるとき — 消すのではなく、札を貼る
作ったものは、いつか使わなくなります。 そのときのやり方を、先に知っておいてください。
基本は deprecate(非推奨にする)
これをすると、そのパッケージを入れた人の画面に、そのメッセージが出ます。
npm warn deprecated @あなたのユーザー名/mdtoc@0.1.1: メンテナンスを終了しました。...
消えてはいません。すでに使っている人は、そのまま動き続けます。 新しく入れようとする人と、更新する人だけが警告を見ます。
これが正しいやめ方です。 移行先があるなら、必ずメッセージに書いてください。
特定のバージョンだけを非推奨にすることもできます。
取り消しは、空文字を渡します。
unpublish は、原則できません
これは、条件を満たさない限り拒否されます。 大まかには「公開してすぐ」か「誰にも依存されておらず、ほとんどダウンロードされておらず、管理者が自分一人」のときだけです。正確な条件は変わるので、必ず公式のポリシーを読んでください。
なぜ、こんなに厳しいのか。
過去に、広く使われていた小さなパッケージが取り下げられ、世界中のビルドが同時に壊れたことがあります。 あなたの
package-lock.jsonに書かれた依存が、ある朝、レジストリから消えている。それが起きます。
npm がやったのは、「一人の判断で、他人の環境を壊せないようにする」ことです。
そして、消せたとしても:
- そのバージョン番号は、二度と使えません
- 名前も、すぐには取り戻せません
- すでに入れてしまった人の手元からは、消えません
だから、⑥の確認が要るのです。 出す前が唯一の分岐点で、出したあとには戻る道がありません。
⑨ 公開しないという選択 — こちらも同じ重さです
ここまで読んで、「publish しない」と決めるのは、まったく正しい判断です。
実際、あなたが作ったスクリプトの大半は、公開すべきではありません。 自分の環境に依存していたり、自分のデータの形を前提にしていたりするからです。公開しない道は3本あります。全部、いま作った mdtoc にそのまま使えます。
A. npm link のまま使う(自分だけ)
②でやった状態を、そのまま続けます。 どこからでも mdtoc と打てて、直せば即反映されます。公開の必要は、ここには1つもありません。
別のマシンでも使いたくなったら:
これだけです。 更新は git pull だけで済みます。
B. GitHubのURLから直接入れる(人に渡す)
npm に出さなくても、npm install の対象にできます。
または package.json の依存に、こう書けます。
{
"dependencies": {
"mdtoc": "github:あなたのユーザー名/mdtoc#v0.1.1"
}
}
| 良いところ | 気をつけるところ |
|---|---|
| npmアカウントが要らない | タグを指定しないと、ブランチの先頭を取ってくる(中身が黙って変わる) |
| プライベートリポジトリでも使える(鍵があれば) | 入れる側に Git が必要 |
| 名前を1つも消費しない | npmjs.com では検索されない |
#v0.1.1 のようにタグを付けてください。 付けないと、レジストリの回で書いた latest と同じ問題が起きます。「同じ指定なのに中身が違う」です。
C. npm pack で作った1ファイルを渡す
mdtoc-0.1.1.tgz
この .tgz を、そのまま渡せます。
これは、社内やチームで配るときの現実的な手段です。 インターネットに出せないコードでも、これなら配れます。レジストリの回で立てたプライベートレジストリの、いちばん素朴な版だと思ってください。
D. スコープ付きで、非公開のまま公開する
npm publish で、npmjs.com に置きながら、限られた人にしか見せないこともできます。
これは有料プランが必要です。 ただし、「会社で使う」という状況では、これがいちばん普通の答えです。組織のメンバーだけが npm install できます。
選び方
| こういうとき | これ |
|---|---|
| 自分しか使わない | A(npm link) |
| 数人に渡したい / 会社の外に出せない | B(GitHub直指定)か C(.tgz) |
| 組織で共有したい | D(restricted)か、自前レジストリ |
| 世界の誰かの役に立つ、と本気で思える | 公開する |
いちばん下だけが publish です。 そして、そこに当てはまらないものを publish しないのが、レジストリを綺麗に保つということです。
⑩ やりすぎない
公開すると、足したくなります。 先に線を引いておきます。
| 足したくなるもの | いま要るか |
|---|---|
| 引数解析ライブラリ(commander / yargs) | まだ。 オプションが5個を超えてから |
| 色付き出力(chalk など) | 要注意。 色コードはパイプに流すと文字化けの元です。付けるなら process.stdout.isTTY で判定して、パイプのときは無色にする |
| TypeScript | 良い選択だが、ビルド工程が増える。動くものができてから |
| プログレスバー | 一瞬で終わるものには要らない |
| 設定ファイル対応 | オプションで足りているうちは要らない |
| テスト | これは足してください。 公開した瞬間から、壊すと他人が困ります |
依存を1つ入れるたびに、それを入れた全員に、その依存が押し付けられます。
CLIツールは、依存が少ないほど価値が上がります。
npx あなたのツールが数秒で終わるか、30秒かかるかは、dependenciesの行数で決まります。mdtocは依存ゼロで書けました。それは自慢していいことです。
つまずいたところ
1. コードブロックの中の # を、見出しとして拾っていた
最初のバージョンには、inFence の判定がありませんでした。 動かしてみたら、目次にこういう行が並びました。
- [!/usr/bin/env node](#usrbinenv-node)
- [--- 入力を読む ---...](#--------)
シェルのコメント(#)と、シバンを、見出しだと思っていました。
技術記事のMarkdownには、コードブロックが大量に入ります。その中の # は、ほぼ全部コメントです。 ④のコードでコードブロックの開始・終了を数えるようにしたら、直りました。
この記事のMarkdownで試したから見つかりました。 サンプルの短いファイルだけで試していたら、公開してから気づいていたはずです。実際に使う予定の、いちばん大きくて汚いデータで試してください。
2. npm link したのに command not found
mdtoc: command not found
bin に書いたパスが違っていました。 "./bin/mdtoc.js" と書くべきところで、ファイル名の綴りを間違えていて(./ を付けるかどうかは関係ありません。どちらもパッケージ直下からのパスとして扱われます)、リンクは作られるのに、リンク先が存在しない状態になっていました。
確かめ方はこれです。
リンク先が赤く表示されたら、そこに何も無いという意味です。 bin を直して、npm unlink -g mdtoc してから npm link し直しました。
3. npm login でブラウザが開かず、止まった
⑥に書いた通りです。 VMにブラウザが無いので、Press ENTER to open in the browser... の先に進みませんでした。
表示されたURLをコピーして、ホストのWindowsのブラウザに貼ったら通りました。 VS Code の Remote-SSH で繋いでいれば、ターミナルのURLをそのままクリックできます。
4. npm pack に toc.md と .env が入っていた
⑥に書いた本番の事故です。
.gitignore に .env を書いてあったので安心していたのですが、.npmignore を後から作ったせいで、.gitignore が無視されていました。
これに気づいたのは npm pack --dry-run を打ったからです。 打たずに publish していたら、取り消せない形で世界に出ていました。
やったこと: .npmignore を消して、files: ["bin/"] に切り替えました。除外を書くのをやめて、入れるものだけを書く形にしました。
5. スコープを付けたら 402 で断られた
npm error code E402
npm error 402 Payment Required - PUT https://registry.npmjs.org/@user%2fmdtoc - You must sign up for private packages
「お金を払え」と読めますが、そうではありません。 スコープ付きは既定で非公開扱いなので、「非公開にするなら有料です」と言われているだけです。
これで通りました。 そして、この仕様のおかげで、うっかり公開する事故が起きません。 一度こう設定すれば、package.json に書いて固定できます。
{
"publishConfig": {
"access": "public"
}
}
6. --version に飾りを付けて、あとで困った
最初は、こう出していました。
mdtoc version 0.1.0
別のスクリプトからバージョンを取り出そうとして、切り出す羽目になりました。
数字だけにしました。 CLIの出力は、人が読むものである前に、機械が読むものです。
後片づけ
公開まで進まなかった場合、消すものはこれだけです。
何も返らなければ、外れています。フォルダごと消すなら:
ログインしたままにしたくないとき:
公開してしまった場合は、フォルダを消してもパッケージは残ります。
- 使わないなら
npm deprecateで札を貼ってください(⑧) unpublishは最終手段です。 そして、たいてい通りません
認証情報の置き場所も知っておいてください。 ホームディレクトリの .npmrc に、npm のトークンが平文で入っています。2025年12月の変更以降、npm login のセッションは2時間で切れますが、期限内は publish に使えるので、扱いは同じです。
このファイルを、間違ってもリポジトリにコピーしないでください。 シークレット管理の回で扱ったものと、まったく同じ危険度のファイルです。
まとめ — 理解できたこと
- CLIツールの中身は、普通のスクリプト。 違うのは
#!/usr/bin/env nodeの1行と、package.jsonのbinだけ。npm linkを使えば、公開せずにnpm install -gと同じ状態が作れる #!/usr/bin/env nodeと書くのは、node の場所が人によって違うから。 nvm を使っている時点で、あなたの環境のパスは他人と違うprocess.argvの最初の2つは node 自身とスクリプトの場所。 自分の引数はslice(2)から--helpと--versionが無いツールは、他人には使えない。 そして半年後の自分が、その他人になる。--versionは数字だけを出す- 結果は標準出力、メッセージは標準エラー。 これを守るとパイプに繋がる。
console.logで進捗を出した瞬間、そのツールはパイプで使えなくなる - 終了コードを返さないツールは、常に成功したことになる。 どんなにエラーを表示しても、CIは緑のまま通る。
0が成功 npm publishは取り消せない。 バージョン番号は二度と使えず、名前もすぐには取り戻せず、入れてしまった人の手元からは消えない.gitignoreは、.npmignoreを作った瞬間に完全に無視される。 両方効くのではなく、片方に切り替わる。だから除外を数える(.npmignore)のではなく、入れるものを数える(files)npm pack --dry-runは、公開前の唯一の目視の機会。 ここを飛ばすと、取り消せない形で出る- 2要素認証をかけないと、乗っ取りの被害者は自分ではなく、自分を信頼した全員になる。 範囲は必ず Authorization and writes
- バージョン番号は感想ではなく約束。
^1.4.2と書いた人は「1.x の間は壊れない」を信じている。壊す変更は、どんなに小さくてもメジャー - やめるときは
deprecateで札を貼る。unpublishは原則できないし、できても他人の環境を壊す - 公開しないという選択は、対等な選択。
npm link/ GitHub直指定 /.tgzを渡す / スコープ付きの非公開。「世界の誰かの役に立つ」と本気で思えるものだけを publish する - 依存を1つ入れると、入れた全員にそれが押し付けられる。 依存ゼロで書けたなら、それは価値
そして、いちばん大きい変化はこれです。
npm install -gの向こう側が、想像の対象ではなくなりました。
これまであなたが使ってきたツールは、誰かがこの手順を通って置いたものです。名前を調べ、中身を確かめ、2要素認証をかけ、取り消せないボタンを押した人がいます。そして、その人も、npm pack --dry-run の出力を1行ずつ見たはずです。
参考リンク
- npm Docs — package.json の bin フィールド
- npm Docs — npm publish
- npm Docs — npm link
- npm Docs — npm pack
- npm Docs — npm version
- npm Docs — npm deprecate
- npm Docs — 公開したパッケージの取り下げポリシー
- npm Docs — 2要素認証について
- npm Docs — 2要素認証の設定
- npm Docs — スコープについて
- npm Docs — スコープ付きパッケージの公開
- npm Docs — package.json の files フィールド
- セマンティック バージョニング 2.0.0(日本語)
- Node.js 公式ドキュメント — process.argv
- Node.js 公式ドキュメント — process.exit
- Node.js 公式ドキュメント — parseArgs(標準の引数解析)
- Command Line Interface Guidelines(CLI設計の指針・英語)
- roadmap.sh — Node.js
- roadmap.sh — Full Stack Developer
最後に1つ。 この記事で作った
mdtocを、公開しなくても構いません。npm linkして、明日から実際に使ってください。 公開されていないツールでも、あなたの作業が速くなったなら、それは完成しています。
次に読む
この記事は 【第9段階】作品を1つ完成させる の 6 / 10 本目です。
| 記事 | |
|---|---|
| ← 前の記事 | 他人は5分しか見ない — READMEと技術選定 |
| → 次の記事 | 他人のページを書き換える — ブラウザ拡張を作る |
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
作品づくり。npm への公開は roadmap.sh の項目ではなく、道具の使い方の話。

コメント