Wie @yarlisai-Pakete eingebunden werden

Jedes @yarlisai/*-Paket wird gleichzeitig auf zwei völlig unterschiedliche Arten eingebunden. Das Verständnis beider Modi erklärt, warum Deployments nie npm berühren, warum es in der lokalen Entwicklung keinen Build-Schritt gibt und warum das Veröffentlichen ein paralleler Prozess und keine Deploy-Abhängigkeit ist.

Die Exports-Map

Beide Modi hängen an derselben konditionalen exports-Map, die in jedem Paket vorhanden ist:

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

Die bun-Bedingung wird unter der Bun-Runtime zuerst aufgelöst und zeigt direkt auf den TypeScript-Quellcode. Alle anderen Konsumenten (Node, Bundler, die import/default unterstützen) erhalten die kompilierte dist/-Ausgabe.

Interner Modus — Workspace-Quellcode

Innerhalb des Monorepos deklarieren Apps Pakete als "@yarlisai/<pkg>": "workspace:*". Bun-Workspaces verlinken node_modules/@yarlisai/<pkg> per Symlink auf packages/<pkg>/, und die bun-Exportbedingung löst Importe direkt zu src/index.ts auf:

• Kein Build-Schritt in der Entwicklung. Das Bearbeiten von packages/email/src/ lädt die App sofort neu — es gibt kein dist/ zum Neubauen und kein veraltetes Artefakt, dem man hinterherjagen müsste.
• Docker/CD baut aus dem Quellcode. Das Produktions-Image (Dockerfile.cloudrun) kopiert den Workspace, baut mit turbo, und Next.js standalone output tracing bündelt genau die Paketdateien, die die App importiert.
• npm wird bei Deployments nie kontaktiert. Ein Registry-Ausfall, eine zurückgezogene Version oder ein fehlgeschlagenes Publish können ein Deployment nicht gefährden — die App liefert aus, was im Git-Tree vorhanden ist.

Externer Modus — npm-Tarballs

Externe Konsumenten installieren von npm und erhalten das veröffentlichte Tarball:

• Das Tarball enthält dist/ (plus README.md und LICENSE) — niemals src/. Die Auflösung erfolgt über die import/default-Bedingungen zu dist/index.js, mit Typen aus dist/index.d.ts.
• Builds führen tsc und anschließend tsc-alias --resolve-full-paths aus, sodass emittierte Importe explizite .js-Erweiterungen tragen — Node ESM ist dabei streng, auch wenn Bundler es nicht sind.
• Zum Zeitpunkt der Veröffentlichung werden workspace:*-Abhängigkeitsbereiche vom Publish-Workflow in echte Semver-Bereiche (^x.y.z) umgeschrieben. Ohne diese Umschreibung würde npm install aufgrund ungültiger Semver scheitern.
• Pakete werden derzeit als restricted in der Yarlis-npm-Org veröffentlicht; öffentlicher Zugriff ist geplant.

Warum beides

• Deployments sind unabhängig von npm. Probleme beim Veröffentlichen (und npm-Ausfälle) blockieren nie die Auslieferung des Produkts — die App konsumiert den Quellcode über den Workspace.
• Sofortige Entwicklungsiteration. Konsumption auf Quellebene bedeutet, dass paketübergreifende Änderungen ein einziger Hot-Reload sind und kein Build-Link-Neustart-Zyklus.
• Der Framework-Track ist entkoppelt. Versionierung, Changelogs und das Veröffentlichen laufen über Changesets und dedizierte Publish-Workflows in eigenem Rhythmus, ohne Koordination mit App-Releases.

Der Preis des Dual-Mode ist, dass interne Konsumption externe Fehler verbergen kann — genau dafür gibt es das publint-Gate und den externen Smoke-Test.

Siehe auch

• Framework-Übersicht
• ADR 0007 — Port/Adapter-Vertrag
• Access-Flip-Runbook: docs/maintenance/npm-public-launch.md im Monorepo