npm publishせずに即連携！Yalcでローカルパッケージ開発を爆速にする方法（bun & npm対応）

Kivaでエンジニアをしている吉野です！

今回は、ローカルで開発中の npm パッケージを、アプリ側で素早く試したいときに便利なツール Yalc の使い方と、実際の活用フローを紹介します！
https://github.com/wclr/yalc

🥑 この記事で紹介すること

• Yalcって何？
• なぜYalcを使うのか？
• 実際にどんな開発フローで使っているか（npm / bun 両方）
• パッケージ開発の効率を上げるaliasの使い方

など、誰でも試せるように置き換えやすいコマンド例付きで紹介していこうと思います！

📦 Yalcとは？

Yalc は、自分で開発中の npm パッケージを 公開せずに、ローカル環境で他のプロジェクトに組み込んで試せる 便利な仕組みです。

ざっくりいうと：

• ビルドしたパッケージを .yalc という専用フォルダに保存
• 他のプロジェクトから yalc add で簡単にインストール可能
• 修正したら yalc push で即反映できて、すぐ手元で確認できる

🤔 なぜ Yalc を使うの？

✅ よくある代替手段

方法	特徴	問題点
npm link	グローバルにリンク。即時反映される	他の依存と競合しやすく、不安定
npm pack	tgzでパッケージを固めてinstall	手間が多く、毎回面倒
yalc	パッケージを .yalc に仮想publish	安定・速い・安全！おすすめ ✅

🛠️ 実践フロー：ローカル開発で使う手順

ここでは、実際に bun または npm を使って開発しているときの Yalc の使い方を紹介します。複数のプロジェクトを連携させながら開発している方にはとても便利な方法です。

🧩 パッケージ側（提供元）

まずは、自作の npm パッケージを yalc に登録して使える状態にします。

# Yalc をインストール（初回のみ）
yarn global add yalc

# パッケージをビルド（例: bun or npm）
bun run build       # または npm run build

# Yalc に登録（仮想 publish）
yalc publish

上記のコマンドを実行すると、パッケージが ~/.yalc/ に保存され、他プロジェクトから参照できるようになります。

✅ yalc publish をしていないと、後述の yalc add がエラーになるので、先にパッケージ側で登録を済ませておきましょう。

💻 アプリ側（利用先）

次に、開発中のパッケージを実際に使うアプリ（または別プロジェクト）に組み込みます。

# Yalc からパッケージを追加
yalc add @your-scope/your-package-name

@your-scope/your-package-name は、実際のパッケージ名に置き換えてください。
（スコープがない場合は your-package-name だけでもOKです）

📦 この操作により、package.json の該当箇所が以下のように書き換わります：

- "@your-scope/your-package-name": "npm:@your-scope/your-package-name@0.0.x"
+ "@your-scope/your-package-name": "file:.yalc/@your-scope/your-package-name"

.yalc/ ディレクトリがプロジェクト内に作成され、ローカルに登録されたパッケージがコピーされます。

※ これは node_modules とは別のディレクトリで、yalc 専用の仮想パッケージ置き場です。

⚡️ 依存をインストール （アプリ側で）

bun install       # または npm install

通常は yalc add だけで動作しますが、依存関係に変化があった場合や型定義がうまく参照されない場合には、再インストールするのが安心です。

🚀 アプリ起動

bun run dev       # または npm run dev

これで、ローカルで開発した公開前のパッケージをアプリ側に取り込んで確認することができるようになりました！

🔄 パッケージ修正 → 再反映 （パッケージ側で）

ローカル開発中は、以下の手順でパッケージの修正を即反映できます：

# パッケージのディレクトリへ移動
cd <your package directory>

# 修正したコードをビルド
bun run build       # または npm run build

# アプリ側に変更を反映
yalc push

yalc push を実行するだけで、すでに yalc add しているアプリ側に即時で変更が伝わります。

✨ Tips：もっと効率化したいなら alias 登録！

毎回手動で cd, build, push, install, run を繰り返すのは面倒…という方は、以下のような alias を .zshrc や .bashrc に登録すると便利です。（単一パッケージ向け）

# dev local package（bunの場合）
alias pkglocal='
cd <your packages directory> &&
bun run build &&
yalc push &&
cd <your application directory> &&
bun install &&
bun run dev
'

※ <your packages directory> や <your application directory> は自分の環境に置き換えてください。

✅ 登録＆反映方法

# .zshrc や .bashrc に追記後
source ~/.zshrc    # または source ~/.bashrc

# 実行は1コマンドでOK！
pkglocal

これで毎回手動で操作することなく、pkglocalをターミナルで実行するだけで素早くローカルパッケージの反映と確認ができるようになります！

🧹 使い終わったら

作業が終わったら、アプリ側で Yalc の参照を削除し、元の npm パッケージに戻します。

# yalc で追加したパッケージを削除
yalc remove @your-scope/your-package-name

# 必要であれば、package.json の該当バージョンを手動で npm 版に戻す
# 例: "file:.yalc/@your-scope/your-package-name" → "npm:@your-scope/your-package-name@0.0.x"

# 依存関係を再インストール
bun install   # または npm install

yalc remove は .yalc/ のリンクを解除しますが、package.json の依存はそのまま残ることがあります。
念のため、file:.yalc/... の記述が元の npm 依存（例: npm:@your-scope/your-package-name@x.y.z）に戻っているか確認し、必要に応じて書き直しましょう。

🧼 補足：node_modules を削除する必要はある？

基本的に yalc push で変更が即反映されるため、rm -rf node_modules のようなキャッシュ削除は不要です。

ただし、

• 型定義がうまく更新されない
• 複数の yalc パッケージが競合する
• bun.lockb まわりでバグっぽい挙動が出る

といった場合には、以下のようにリセットしても良いでしょう。

rm -rf node_modules .cache  # 必要に応じて bun.lockb も削除
bun install

🎨 まとめ

Yalc は、ローカルで開発中の npm パッケージを npm に publish せずに他プロジェクトで試せる、軽量で便利なツールです。

• npm link を使用していた方
• 毎回 npm publish していた方
• bun や npm で開発している方

こんな方には特におすすめです！

他にも「こういう方法も便利だよ」「自分はこう使ってる」などがあれば、ぜひ気軽にコメントで教えてください。
最後まで読んでいただき、ありがとうございました！