biome（npm）の使い方 — プロジェクト単位で環境変数を安全に管理するCLIツール

⚠️ 注意: この記事で解説する biome（npm パッケージ）は、近年注目を集めている Rust 製のリンター/フォーマッター「Biome (biomejs)」とはまったく別のパッケージです。名前が同じですが、用途も開発元も異なります。本記事は環境変数管理ツールとしての biome（v0.3.3）を扱います。

---

一言でいうと

biome は、プロジェクトごとに環境変数をローカルファイル（~/.biome）で一元管理し、シークレットをソースコードから完全に分離するための CLI ツールです。dotenv のようにファイルを読み込むのではなく、専用のシェルを起動して環境変数を注入するアプローチを取ります。

---

どんな時に使う？

1. 複数プロジェクトで異なる環境変数セットを切り替えたい時 — プロジェクトAとプロジェクトBで異なる API キーやデータベース接続情報を持ち、ワンコマンドで切り替えたい場合に便利です。
2. チーム開発でシークレットをリポジトリに含めたくない時 — Biomefile（プロジェクト名だけを記載）はコミットし、実際の秘密情報は各開発者のローカル（~/.biome/）に保持する運用ができます。
3. 新メンバーのオンボーディングを効率化したい時 — Biomefile にテンプレートを定義しておけば、biome init 実行時に必要な環境変数の入力をインタラクティブに促せます。

---

インストール

biome はグローバルにインストールして CLI として使うのが基本です。

# npm
npm install -g biome

# yarn
yarn global add biome

# pnpm
pnpm add -g biome

注意: v0.3.3 時点の情報です。最新バージョンでは挙動が変わっている可能性があります。

---

biome の基本的な使い方

最もよく使うワークフローは「初期化 → 変数追加 → シェル起動」の3ステップです。

# 1. プロジェクトの環境を初期化（カレントディレクトリに Biomefile が作成される）
biome init my-api

# 2. 環境変数を追加
biome add my-api DATABASE_URL="postgres://localhost:5432/mydb"
biome add my-api API_KEY="sk-xxxxxxxxxxxx" NODE_ENV="development"

# 3. 環境変数が注入されたシェルを起動
biome use my-api

# シェル内で確認
echo $DATABASE_URL   # => postgres://localhost:5432/mydb
echo $API_KEY        # => sk-xxxxxxxxxxxx

この時点でのファイル構成は以下のようになります。

プロジェクトルート/
  Biomefile              ← コミット可能（プロジェクト名のみ）

~/.biome/
  my-api.json            ← コミットしない（実際のシークレット）

// Biomefile
{
  "name": "my-api"
}

// ~/.biome/my-api.json
{
  "DATABASE_URL": "postgres://localhost:5432/mydb",
  "API_KEY": "sk-xxxxxxxxxxxx",
  "NODE_ENV": "development"
}

---

よく使う API（コマンド）

1. biome init — プロジェクトの初期化

# 基本
biome init my-project

# テンプレート URL を指定してチーム共有用の初期値を適用
biome init my-project http://example.com/template.json

カレントディレクトリに Biomefile が生成され、~/.biome/my-project.json が作成されます。テンプレートが Biomefile に定義されている場合は、対話的に値の入力を求められます。

2. biome add — 環境変数の追加

# 単一の変数
biome add my-project SECRET_KEY="abc123"

# 複数の変数を一度に追加
biome add my-project FOO=bar BAZ="I'm a teapot"

3. biome use — 環境変数を注入したシェルの起動

biome use my-project
# => $SHELL の新しいインスタンスが起動し、すべての変数が設定済み

# シェル内で biome（引数なし）を実行すると現在の環境を確認できる
biome

exit でシェルを抜けると、注入された環境変数はすべて消えます。ホストのシェルを汚しません。

4. biome edit — 環境変数の直接編集

biome edit my-project
# => $EDITOR（vim, nano など）で ~/.biome/my-project.json を開く

JSON を直接編集できるため、変数の削除や一括変更に便利です。

5. biome vars — 環境変数の一覧表示

biome vars my-project
# => 設定されている全変数を標準出力に表示

CI/CD パイプラインでのデバッグや、現在の設定確認に使えます。

---

$include による環境の継承

biome の強力な機能として、他の環境を継承（インクルード）できます。

// ~/.biome/my-project.json
{
  "$include": ["common-aws", "common-db"],
  "APP_NAME": "my-project",
  "NODE_ENV": "development"
}

// ~/.biome/common-aws.json
{
  "AWS_ACCESS_KEY_ID": "AKIA...",
  "AWS_SECRET_ACCESS_KEY": "...",
  "AWS_REGION": "ap-northeast-1"
}

// ~/.biome/common-db.json
{
  "DATABASE_URL": "postgres://localhost:5432/shared"
}

biome use my-project を実行すると、common-aws と common-db の変数もすべて注入されます。共通設定を複数プロジェクトで使い回す際に非常に便利です。

---

テンプレート機能によるオンボーディング

Biomefile にテンプレートを定義しておくと、新しいメンバーが biome init した際にインタラクティブに値を入力できます。

// Biomefile（リポジトリにコミット）
{
  "name": "my-project",
  "template": {
    "DATABASE_URL": "postgres://localhost:5432/mydb",
    "API_KEY": "",
    "NODE_ENV": "development"
  }
}

新メンバーが biome init を実行すると、各キーについてデフォルト値付きのプロンプトが表示されます。

---

類似パッケージとの比較

選定の目安:

• Node.js プロジェクトでシンプルに使いたい → dotenv
• シェルレベルで自動切り替えしたい → direnv
• チーム開発でシークレット分離とテンプレートが欲しい → biome
• npm scripts で OS 差異を吸収したいだけ → cross-env

---

注意点・Tips

1. パッケージ名の混同に注意

冒頭でも述べましたが、Rust 製リンター/フォーマッターの Biome（@biomejs/biome） とは完全に別物です。npm install biome と npm install @biomejs/biome を間違えないようにしてください。

2. ~/.biome/ ディレクトリのバックアップ

すべてのシークレットが ~/.biome/ に集約されるため、このディレクトリの紛失はすべての環境変数の喪失を意味します。暗号化バックアップを取っておくことを推奨します。

3. .gitignore に Biomefile は含めない

Biomefile にはプロジェクト名（とテンプレート）しか含まれないため、コミットして OK です。一方、~/.biome/*.json はホームディレクトリにあるため通常はリポジトリに含まれませんが、念のため確認しましょう。

4. $EDITOR の設定

biome edit は $EDITOR 環境変数を参照します。未設定の場合はエラーになることがあるため、事前に設定しておきましょう。

export EDITOR=vim  # ~/.bashrc や ~/.zshrc に追加

5. カスタム設定

保存先やファイル名を変更したい場合は、以下の環境変数で制御できます。

6. メンテナンス状況について

このパッケージは更新頻度が低く、最終更新からかなりの時間が経過しています。新規プロジェクトで採用する場合は、dotenv や direnv など、より活発にメンテナンスされている代替手段も検討してください。

---

まとめ

biome は、環境変数をプロジェクトのソースコードから完全に分離し、~/.biome/ で一元管理するための CLI ツールです。$include による環境の継承やテンプレート機能など、チーム開発を意識した設計が特徴的です。ただし、メンテナンス状況を考慮すると、現在は dotenv や direnv のほうが実用的な選択肢となるケースが多いでしょう。シークレット管理のアーキテクチャとして「コードとシークレットの分離」という思想自体は参考になるため、自チームの運用に合わせて検討してみてください。