npm publish は取り消せない — CLIツールを配る

CLIツールを配る。ターミナル画面と配送用のパッケージ箱、確認のチェックリスト。

npm publish は取り消せません。CLIツールを作り、公開する前に確認することを全部確かめます。

前回: 他人は5分しか見ない — READMEと技術選定

この回は、実際に世界に向けて公開します。そして、その操作は取り消せません。 公開まで進むかどうかは、⑥まで読んでから決めてください。⑨に「公開しない」やり方をまとめてあります。どちらも同じ重さの選択です。

作業場所は 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 で渡す / スコープ付きで組織内に限る

この記事でやること

  1. 小さいCLIツールを1つ作る(Markdownの見出しを一覧にする mdtoc)。npm link で手元に入れて動かす
  2. process.argv の中身をそのまま表示させる。 そのうえで --help と --version を付ける
  3. 標準入力から読めるようにして、| で繋ぐ。 メッセージを標準エラーに追い出す
  4. 終了コードを返す。 GitHub Actions から呼んで、赤くする
  5. 公開の直前に、取り返しのつかないことを確認する。 名前を調べ、npm pack で中身を見て、2要素認証をかける
  6. npm publish する。 そのあと npm view で、世界から見えていることを確かめる
  7. バージョンを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つあります。

  1. 自分が実際に使う。 このサイトの記事も、READMEも、Markdownです。見出しの一覧が欲しい場面は実際にありました
  2. 入力があって、出力がある。 だからパイプに繋がる形にできます。⑤でそこをやります
  3. 失敗する余地がある。 ファイルが無い、読めない、見出しが1つも無い。だから終了コードを返す意味があります

「1日で作れて、明日から使うもの」 が条件です。これより大きいものにしないでください。

もう1つの候補を書いておきます。 hitokoto のデータベースをバックアップする hitokoto-backup のような、自分専用の道具もCLI向きです。 ただし世界に公開する題材ではありません。(自分にしか使えないものを npm に出しても、名前を1つ潰すだけです。⑨に、そういうものの配り方を書きます)


② CLIの中身は、普通のスクリプトです

ここが、この記事でいちばん拍子抜けするところです。

CLIツールと、あなたがこれまで書いてきた node なんとか.js の間に、特別な仕組みはありません。 違うのは2つだけです。

普通のスクリプトCLIツール
1行目何も無い#!/usr/bin/env node がある
package.jsonmain があるbin がある

それだけです。順に見ます。

まず、置き場所を作る

VMの中で打ちます。

bash
$ mkdir -p ~/mdtoc/bin
$ cd ~/mdtoc
$ git init
$ npm init -y

npm init -y で package.json ができます。中身はあとで全部書き直します。

中身を書く

bash
$ nano ~/mdtoc/bin/mdtoc.js

まずは、いちばん短い形から始めます。 引数も何も見ません。

#!/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 の場所は、こういう所にあります。

bash
$ which node
/home/ubuntu/.nvm/versions/node/v22.11.0/bin/node

この場所は、人によって全部違います。 バージョンを切り替えれば、あなた自身の中でも変わります。ここを直接書いたら、他人の環境では動きません。

/usr/bin/env node は、「PATH の中から node という名前を探して、見つかったものを使え」という意味です。だから nvm でも、apt で入れた node でも、macOS でも動きます。

#! は、ファイルの1行目の、いちばん先頭でなければ効きません。 前に空行やコメントがあると、ただの文字列になります。

実行できるようにする

bash
$ chmod +x ~/mdtoc/bin/mdtoc.js
$ ~/mdtoc/bin/mdtoc.js
mdtoc が起動しました

node と打たずに動きました。 パーミッションの回でやった x が、ここで効いています。

bin フィールドを書く

いまはフルパスで打っています。どこからでも mdtoc と打てるようにします。

bash
$ nano ~/mdtoc/package.json
{
  "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 で、公開せずに手元へ入れる

ここが、この記事で最初に「おっ」となる所です。

bash
$ cd ~/mdtoc
$ npm link
added 1 package in 234ms

別のフォルダに移動して、打ちます。

bash
$ cd ~
$ mdtoc
mdtoc が起動しました

npm install -g で入れたツールと、まったく同じ形で動きました。 公開はしていません。

何が起きたのか。 npm link は、グローバルの bin 置き場にシンボリックリンク(実体への近道)を作ります。

bash
$ which mdtoc
$ ls -l $(which mdtoc)
/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 のまま使い続けるのは、まったく正しい選択です。⑨に書きます。

外すときは、これです。

bash
$ npm unlink -g mdtoc

③ 引数は process.argv に入っている — 最初の2つに注意

ここは、実際に表示させて確かめてください。 説明を読むより速いです。

bash
$ nano ~/mdtoc/bin/mdtoc.js
#!/usr/bin/env node

console.log(process.argv);

打ちます。

bash
$ mdtoc README.md --depth 3
[
  '/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/nodenode 自身の場所
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か所にしか置きません。

確かめます。

bash
$ mdtoc --help
$ mdtoc --version
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 を入れてください。

動かす

bash
$ cd ~/mdtoc
$ mdtoc README.md

そして、ここが本題です。パイプで繋ぎます。

bash
$ cat README.md | mdtoc
$ mdtoc README.md | head -5
$ mdtoc README.md > toc.md
$ mdtoc README.md | grep インストール

grep や head と、同じように繋がりました。

メッセージが混ざらないことも確かめてください。

bash
$ mdtoc 存在しないファイル.md > out.txt
$ cat out.txt
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 です。「エラーの数がゼロ」と考えると覚えられます。

確かめます。

bash
$ mdtoc README.md > /dev/null
$ echo $?
$ mdtoc 存在しないファイル.md 2> /dev/null
$ echo $?
0
1

なぜこれが重要なのか。

終了コードは、人ではなく機械が読みます。

  • mdtoc a.md && echo OK — 成功したときだけ次を実行する
  • GitHub Actions は、ステップの終了コードが 0 以外ならジョブを失敗(赤)にします
  • ESLint や Prettier が CI を止められるのも、これだけが理由です

終了コードを返さないツールは、必ず成功したことになります。 どんなにエラーメッセージを出しても、CIは緑のまま通ります。

CIから呼んでみる

~/mdtoc/.github/workflows/ci.yml を作ります。

bash
$ mkdir -p ~/mdtoc/.github/workflows
$ nano ~/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. 名前を調べる

bash
$ npm view mdtoc

取られていると、こう返ります。

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 は、いまいるフォルダの中身を、あなたが思っているより多く持っていきます。

確かめる方法があります。公開せずに、公開されるものだけを作るコマンドです。

bash
$ cd ~/mdtoc
$ npm pack --dry-run
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 は、書いても入りません)

もう一度確かめます。

bash
$ npm pack --dry-run
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つになりました。

実物を開いて確かめることもできます。

bash
$ npm pack
$ tar tzf mdtoc-0.1.0.tgz
$ rm mdtoc-0.1.0.tgz

公開前チェックの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の中で打ちます。

bash
$ npm login

ここで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 が待つのをやめて先に進みます。

確認します。

bash
$ npm whoami
あなたのユーザー名

6-6. publish する

ここまでの確認が全部済んでいることを、もう一度見てください。

  • [ ] npm view <名前> で、名前が空いている(または、スコープを付けた)
  • [ ] npm pack --dry-run で、入るファイルを1つずつ目で見た
  • [ ] .env や鍵や個人情報が入っていない
  • [ ] package.json に license・description・repository がある
  • [ ] 2要素認証を「Authorization and writes」でかけた
  • [ ] npm whoami が通る

そして、本番の前に、もう1回だけ空打ちできます。

bash
$ npm publish --dry-run

--dry-run は何も送りません。 何が送られるかだけを見せます。

準備ができたら、これを打ちます。

bash
$ npm publish --access public

2要素認証を「writes」にしていれば、6桁の数字を聞かれます。

This operation requires a one-time password.
Enter OTP: 123456
+ @あなたのユーザー名/mdtoc@0.1.0

公開されました。ここから先は、取り消せません。

6-7. 世界から見えていることを確かめる

bash
$ npm view @あなたのユーザー名/mdtoc

そして、いちばん確実なのは、別の場所から入れてみることです。

bash
$ cd /tmp
$ npx @あなたのユーザー名/mdtoc --version

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 を手で書き換えないでください。

bash
$ cd ~/mdtoc
$ git add -A
$ git commit -m "コードブロック内の見出し誤検出を修正"
$ npm version patch
v0.1.1

これが1コマンドで3つやります。

  1. package.json の version を書き換える
  2. その変更をコミットする
  3. v0.1.1 というGitのタグを打つ

作業中の変更が残っていると、npm version は動きません。 先にコミットしてください。これは意地悪ではなく、「どのコードがどのバージョンか」を確実にするためです。

タグも一緒に送ります。

bash
$ git push --follow-tags
$ npm publish

npm publish を打つ前に、必ず npm pack --dry-run をもう一度。ファイルは増えているかもしれません。


⑧ やめるとき — 消すのではなく、札を貼る

作ったものは、いつか使わなくなります。 そのときのやり方を、先に知っておいてください。

基本は deprecate(非推奨にする)

bash
$ npm deprecate @あなたのユーザー名/mdtoc "メンテナンスを終了しました。@別の人/mdtoc2 をお使いください"

これをすると、そのパッケージを入れた人の画面に、そのメッセージが出ます。

npm warn deprecated @あなたのユーザー名/mdtoc@0.1.1: メンテナンスを終了しました。...

消えてはいません。すでに使っている人は、そのまま動き続けます。 新しく入れようとする人と、更新する人だけが警告を見ます。

これが正しいやめ方です。 移行先があるなら、必ずメッセージに書いてください。

特定のバージョンだけを非推奨にすることもできます。

bash
$ npm deprecate @あなたのユーザー名/mdtoc@0.1.0 "0.1.0 には出力が壊れるバグがあります。0.1.1 以上をお使いください"

取り消しは、空文字を渡します。

bash
$ npm deprecate @あなたのユーザー名/mdtoc@0.1.0 ""

unpublish は、原則できません

bash
$ npm unpublish @あなたのユーザー名/mdtoc --force

これは、条件を満たさない限り拒否されます。 大まかには「公開してすぐ」か「誰にも依存されておらず、ほとんどダウンロードされておらず、管理者が自分一人」のときだけです。正確な条件は変わるので、必ず公式のポリシーを読んでください。

なぜ、こんなに厳しいのか。

過去に、広く使われていた小さなパッケージが取り下げられ、世界中のビルドが同時に壊れたことがあります。 あなたの package-lock.json に書かれた依存が、ある朝、レジストリから消えている。それが起きます。

npm がやったのは、「一人の判断で、他人の環境を壊せないようにする」ことです。

そして、消せたとしても:

  • そのバージョン番号は、二度と使えません
  • 名前も、すぐには取り戻せません
  • すでに入れてしまった人の手元からは、消えません

だから、⑥の確認が要るのです。 出す前が唯一の分岐点で、出したあとには戻る道がありません。


⑨ 公開しないという選択 — こちらも同じ重さです

ここまで読んで、「publish しない」と決めるのは、まったく正しい判断です。

実際、あなたが作ったスクリプトの大半は、公開すべきではありません。 自分の環境に依存していたり、自分のデータの形を前提にしていたりするからです。公開しない道は3本あります。全部、いま作った mdtoc にそのまま使えます。

A. npm link のまま使う(自分だけ)

②でやった状態を、そのまま続けます。 どこからでも mdtoc と打てて、直せば即反映されます。公開の必要は、ここには1つもありません。

別のマシンでも使いたくなったら:

bash
$ git clone https://github.com/あなた/mdtoc.git
$ cd mdtoc
$ npm link

これだけです。 更新は git pull だけで済みます。

B. GitHubのURLから直接入れる(人に渡す)

npm に出さなくても、npm install の対象にできます。

bash
$ npm install -g github:あなたのユーザー名/mdtoc

または package.json の依存に、こう書けます。

{
  "dependencies": {
    "mdtoc": "github:あなたのユーザー名/mdtoc#v0.1.1"
  }
}
良いところ気をつけるところ
npmアカウントが要らないタグを指定しないと、ブランチの先頭を取ってくる(中身が黙って変わる)
プライベートリポジトリでも使える(鍵があれば)入れる側に Git が必要
名前を1つも消費しないnpmjs.com では検索されない

#v0.1.1 のようにタグを付けてください。 付けないと、レジストリの回で書いた latest と同じ問題が起きます。「同じ指定なのに中身が違う」です。

C. npm pack で作った1ファイルを渡す

bash
$ npm pack
mdtoc-0.1.1.tgz

この .tgz を、そのまま渡せます。

bash
$ npm install -g ./mdtoc-0.1.1.tgz

これは、社内やチームで配るときの現実的な手段です。 インターネットに出せないコードでも、これなら配れます。レジストリの回で立てたプライベートレジストリの、いちばん素朴な版だと思ってください。

D. スコープ付きで、非公開のまま公開する

npm publish で、npmjs.com に置きながら、限られた人にしか見せないこともできます。

bash
$ npm publish --access restricted

これは有料プランが必要です。 ただし、「会社で使う」という状況では、これがいちばん普通の答えです。組織のメンバーだけが 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

bash
$ mdtoc
mdtoc: command not found

bin に書いたパスが違っていました。 "./bin/mdtoc.js" と書くべきところで、ファイル名の綴りを間違えていて(./ を付けるかどうかは関係ありません。どちらもパッケージ直下からのパスとして扱われます)、リンクは作られるのに、リンク先が存在しない状態になっていました。

確かめ方はこれです。

bash
$ ls -l $(which mdtoc)

リンク先が赤く表示されたら、そこに何も無いという意味です。 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

「お金を払え」と読めますが、そうではありません。 スコープ付きは既定で非公開扱いなので、「非公開にするなら有料です」と言われているだけです。

bash
$ npm publish --access public

これで通りました。 そして、この仕様のおかげで、うっかり公開する事故が起きません。 一度こう設定すれば、package.json に書いて固定できます。

{
  "publishConfig": {
    "access": "public"
  }
}

6. --version に飾りを付けて、あとで困った

最初は、こう出していました。

mdtoc version 0.1.0

別のスクリプトからバージョンを取り出そうとして、切り出す羽目になりました。

数字だけにしました。 CLIの出力は、人が読むものである前に、機械が読むものです。


後片づけ

公開まで進まなかった場合、消すものはこれだけです。

bash
$ npm unlink -g mdtoc
$ which mdtoc

何も返らなければ、外れています。フォルダごと消すなら:

bash
$ rm -rf ~/mdtoc

ログインしたままにしたくないとき:

bash
$ npm logout
$ npm whoami

公開してしまった場合は、フォルダを消してもパッケージは残ります。

  • 使わないなら npm deprecate で札を貼ってください(⑧)
  • unpublish は最終手段です。 そして、たいてい通りません

認証情報の置き場所も知っておいてください。 ホームディレクトリの .npmrc に、npm のトークンが平文で入っています。2025年12月の変更以降、npm login のセッションは2時間で切れますが、期限内は publish に使えるので、扱いは同じです。

bash
$ ls -l ~/.npmrc

このファイルを、間違ってもリポジトリにコピーしないでください。 シークレット管理の回で扱ったものと、まったく同じ危険度のファイルです。


まとめ — 理解できたこと

  • 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行ずつ見たはずです。


参考リンク

最後に1つ。 この記事で作った mdtoc を、公開しなくても構いません。 npm link して、明日から実際に使ってください。 公開されていないツールでも、あなたの作業が速くなったなら、それは完成しています。


次に読む

この記事は 【第9段階】作品を1つ完成させる の 6 / 10 本目です。

記事
← 前の記事他人は5分しか見ない — READMEと技術選定
→ 次の記事他人のページを書き換える — ブラウザ拡張を作る

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

作品づくり。npm への公開は roadmap.sh の項目ではなく、道具の使い方の話。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次