@yarlisaiパッケージの利用方法

すべての@yarlisai/*パッケージは、同時に2つのまったく異なる方法で利用されます。この両モードを理解することで、なぜデプロイがnpmに触れないのか、なぜローカル開発にビルドステップが不要なのか、そしてなぜパッケージ公開がデプロイの依存関係ではなく独立したトラックとして機能するのかが明確になります。

エクスポートマップ

両モードは、すべてのパッケージに存在する同一の条件付きexportsマップを基盤としています：

{
  "exports": {
    ".": {
      "bun": "./src/index.ts",
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "default": "./dist/index.js"
    }
  }
}

bun条件はBunランタイム上で最初に解決され、TypeScriptソースを直接参照します。それ以外のすべてのコンシューマー（Nodeやimport/defaultを尊重するバンドラー）はコンパイル済みのdist/出力を受け取ります。

内部モード — ワークスペースソース

モノレポ内部では、アプリは"@yarlisai/<pkg>": "workspace:*"としてパッケージを宣言します。Bunのワークスペースがnode_modules/@yarlisai/<pkg>をpackages/<pkg>/にシンボリックリンクし、bunエクスポート条件がインポートを直接src/index.tsへ解決します：

• 開発時にビルドステップ不要。 packages/email/src/を編集するとアプリが即座にホットリロードされます — 再ビルドすべきdist/も、追いかけるべき古いアーティファクトも存在しません。
• DockerおよびCDビルドはソースから実行。 本番イメージ（Dockerfile.cloudrun）はワークスペースをコピーし、turboでビルドし、Next.jsのスタンドアロン出力トレーシングがアプリのインポートに必要なパッケージファイルを正確にバンドルします。
• デプロイ時にnpmへのアクセスは発生しない。 レジストリの障害、バージョンの削除、または破損した公開がデプロイを妨げることはありません — アプリはgitツリーにある内容をそのまま配布します。

外部モード — npmタービー

外部のコンシューマーはnpmからインストールし、公開されたタービーを受け取ります：

• タービーにはdist/（およびREADME.mdとLICENSE）が含まれます — src/は含まれません。解決はimport/default条件を経由してdist/index.jsへ向かい、型情報はdist/index.d.tsから取得されます。
• ビルドはtscを実行した後、tsc-alias --resolve-full-pathsを実行するため、出力されるインポートには明示的な.js拡張子が付与されます — バンドラーとは異なり、Node ESMはこれを厳密に要求します。
• 公開時に、workspace:*の依存関係の範囲は公開ワークフローによって実際のsemver範囲（^x.y.z）に書き換えられます。この書き換えがなければ、npm installはsemver不正でエラーとなります。
• パッケージは現在、Yarlis npm orgに対してrestricted（限定公開）として公開されています。パブリックアクセスは今後の予定です。

両モードが必要な理由

• デプロイはnpmの影響を受けない。 公開の問題（およびnpmの障害）が製品のリリースをブロックすることはありません — アプリはワークスペース経由でソースを直接利用しています。
• 開発イテレーションが即時。 ソースレベルの利用により、クロスパッケージの変更は単一のホットリロードで反映されます — ビルド・リンク・再起動のループは不要です。
• フレームワークトラックが分離されている。 バージョン管理、変更履歴、および公開はchangesetsと専用の公開ワークフローを通じて独自のサイクルで運用され、アプリのリリースと調整する必要がありません。

デュアルモードのコストは、内部での利用が外部の破損を隠してしまう可能性があることです — それこそが、publintゲートと外部スモークテストが存在する理由です。

関連情報

• フレームワーク概要
• ADR 0007 — ポート/アダプターコントラクト
• アクセス切り替えのランブック：モノレポ内のdocs/maintenance/npm-public-launch.md