インストール#

Ovellum は単一の npm パッケージ（ovellum）として提供されます。これはビルド時の CLI であり、ランタイムのバンドルには何も追加しません。

必要条件#

Node.js 20 以降。 Node 18 は 2025年4月にサポート終了を迎えました。私たちはこれをサポートしません。
TypeScript または JavaScript のプロジェクト。 Ovellum はどちらでも動作します。マニュアルモードでは tsconfig.json は不要です。

プロジェクトへの追加#

pnpm#

pnpm add -D ovellum

npm#

npm install --save-dev ovellum

yarn#

yarn add --dev ovellum

bun#

bun add -d ovellum

インストールせずに使う#

Ovellum を依存関係としてコミットしたくない場合は、npx を介して実行できます:

npx ovellum build

最初の呼び出しでパッケージがダウンロードされ、キャッシュされます。以降の実行ではキャッシュが再利用されます。これは一度きりの生成には便利ですが、パッケージマネージャーが実行ごとに再解決しなければならないため、CI を遅くします。繰り返しビルドする場合は、 --save-dev でのインストールを推奨します。

グローバルインストール#

プロジェクトローカルの依存関係（上記）を推奨します。プロジェクトごとにバージョンを固定でき、 CI ビルドの再現性を保てます。とはいえ、ovellum コマンドをどこでも使えるようにしたい場合（スキャフォールディングや一度きりのビルドに便利）は、グローバルにインストールしてください:

npm install -g ovellum
# or:
pnpm add -g ovellum
yarn global add ovellum
bun add -g ovellum

その後は npx なしで直接実行できます:

ovellum --version
ovellum build

グローバルインストールは、すべてのプロジェクトに対して単一のバージョンを PATH に置きます。 2つのプロジェクトで異なるバージョンが必要な場合は、それぞれが自分のバージョンを固定できるよう、代わりにプロジェクトローカルのインストールを使ってください。（どちらの場合も Node 20 以降です。）

インストールの確認#

インストール後、次を実行します:

npx ovellum build --help   # project-local; for a global install, drop `npx`

build サブコマンドの概要が表示されるはずです。「command not found」と表示される場合は、インストールしたプロジェクト内にいることと、パッケージマネージャーのバイナリが PATH にあることを確認してください（pnpm では追加で pnpm setup が必要なことがあります）。

アップグレード#

組み込みコマンドが npm で最新リリースを確認し、お使いのパッケージマネージャーで再インストールします:

ovellum upgrade            # プロジェクト内から → プロジェクトのローカルコピーをアップグレード

upgrade は、ローカル依存を見つけたら必ずそちらを対象にします — カレントディレクトリの package.json が ovellum を宣言していれば（あるいは既に node_modules にあれば）、グローバルバイナリで呼び出した場合でも、プロジェクトに対して … add -D ovellum@latest を実行します。そうしたプロジェクトの外にいるときだけ、グローバルインストールにフォールバックします。どちらを更新しようとしているかは表示されます:

Update available: 0.10.0 → 0.10.1 (this project's local dependency).
Run `pnpm add -D ovellum@latest`?

パッケージマネージャーはプロジェクトのロックファイル（pnpm-lock.yaml、yarn.lock など）から判定されるので、pnpm プロジェクトは素のグローバルバイナリからでも pnpm でアップグレードされます。--dry-run でプレビューしたり、--yes で確認をスキップしたりできます。（upgrade リファレンスを参照してください。）また Ovellum は、より新しいバージョンが存在するとき、コマンドの実行後に 「update available」 の通知を一行で表示します（キャッシュされます。設定で update: { check: false } を指定すると無効化できます）。

手動でアップグレードする#

パッケージマネージャーを自分で実行したい場合は、明示的に @latest をインストールしてください:

pnpm add -D ovellum@latest
# or: npm install -D ovellum@latest  ·  yarn add -D ovellum@latest  ·  bun add -d ovellum@latest

なぜ npm update ではなく @latest なのか？ Ovellum はまだ 1.0 より前であり、キャレット範囲 — "ovellum": "^0.9.0"、インストーラーがデフォルトで書き込むもの — は 0.x バージョンでは >=0.9.0 <0.10.0 を意味します。つまりマイナーを固定するのです。そのため npm update ovellum / pnpm update ovellum は 0.9.x のパッチは取得しますが、 0.10.0 には上げてくれません。ovellum@latest をインストールすると範囲が書き換えられ、最新リリースを取得できます。（ovellum upgrade はこれを代わりに行います。）

グローバルインストールの場合は、インストールしたときと同じ方法でアップグレードします: npm install -g ovellum@latest（自分のパッケージマネージャーに置き換えてください）。

グローバル vs. プロジェクトローカル#

ovellum upgrade は宣言されたローカル依存を優先するため、かつての落とし穴 — 素の ovellum upgrade がプロジェクトを固定したままグローバルインストールだけをこっそり更新してしまう — は、通常のプロジェクト内ではもう起きません。判定は単純で、「このディレクトリの package.json は ovellum に言及しているか？」だけです。言及していれば、プロジェクトが優先されます。

知っておくべきエッジケースが 2 つあります:

依存が宣言されていないプロジェクト。 ディレクトリの package.json に ovellum がなく、node_modules にもない場合、upgrade はグローバルインストールとして扱います。先にプロジェクトへ追加（npm install -D ovellum）してから再実行してください。
本当にグローバルを更新したい場合。 Ovellum プロジェクトではないディレクトリから upgrade を実行するか、手動でインストールしてください: npm install -g ovellum@latest。

どちらのコピーを使っているか確認するには:

grep ovellum package.json          # プロジェクトが固定している範囲
npx ovellum --version              # `npx` はローカルコピーを実行

CI へプッシュする？ 更新した package.json とロックファイル（package-lock.json / pnpm-lock.yaml / yarn.lock / bun.lock）の両方をコミットしてください。npm ci のような CI ステップはロックファイルから厳密にインストールするため、ロックファイルが古いまたは存在しないと、CI は古い Ovellum でビルドする（または不一致で失敗する）ことになります。

Ovellum は semver に従います。1.0 より前のリリースでは、マイナーバージョンでも破壊的変更が含まれることがあります。バージョンを上げる前にリリースノートを確認してください。

アンインストール#

pnpm remove ovellum

出力ディレクトリ（dist/、docs/、または output で指定した場所）はあなたのものです。 Ovellum をアンインストールしても、それは手つかずのまま残ります。準備ができたときにいつでも手動で削除できます。