Comment les packages @yarlisai sont consommés

Chaque package @yarlisai/* est consommé de deux manières complètement différentes en même temps. Comprendre ces deux modes explique pourquoi les déploiements ne touchent jamais npm, pourquoi il n'y a pas d'étape de build en développement local, et pourquoi la publication est une piste parallèle plutôt qu'une dépendance de déploiement.

La map d'exports

Les deux modes reposent sur la même map exports conditionnelle, présente dans chaque package :

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

La condition bun est résolue en premier sous le runtime Bun et pointe directement vers la source TypeScript. Tout autre consommateur (Node, bundlers respectant import/default) obtient la sortie compilée dans dist/.

Mode interne — source du workspace

À l'intérieur du monorepo, les applications déclarent les packages avec "@yarlisai/<pkg>": "workspace:*". Les workspaces Bun créent un lien symbolique de node_modules/@yarlisai/<pkg> vers packages/<pkg>/, et la condition d'export bun résout les imports directement vers src/index.ts :

• Pas d'étape de build en dev. La modification de packages/email/src/ recharge l'application à chaud immédiatement — il n'y a pas de dist/ à reconstruire ni d'artefact périmé à gérer.
• Docker / CD build depuis la source. L'image de production (Dockerfile.cloudrun) copie le workspace, compile avec turbo, et le traçage de sortie standalone de Next.js regroupe exactement les fichiers de packages importés par l'application.
• npm n'est jamais contacté lors des déploiements. Une panne du registre, une version supprimée ou une publication cassée ne peut pas bloquer un déploiement — l'application embarque ce qui se trouve dans l'arbre git.

Mode externe — tarballs npm

Les consommateurs externes installent depuis npm et obtiennent le tarball publié :

• Le tarball contient dist/ (ainsi que README.md et LICENSE) — jamais src/. La résolution passe par les conditions import/default vers dist/index.js, avec les types depuis dist/index.d.ts.
• Les builds exécutent tsc puis tsc-alias --resolve-full-paths, de sorte que les imports émis portent des extensions .js explicites — Node ESM est strict à ce sujet, contrairement aux bundlers.
• Au moment de la publication, les plages de dépendances workspace:* sont réécrites en plages semver réelles (^x.y.z) par le workflow de publication. Sans cette réécriture, npm install échouerait sur un semver invalide.
• Les packages sont actuellement publiés en mode restricted dans l'organisation npm Yarlis ; un accès public est prévu.

Pourquoi les deux modes

• Les déploiements sont immunisés contre npm. Les problèmes de publication (et les pannes npm) ne bloquent jamais la mise en production — l'application consomme la source via le workspace.
• Itération de développement instantanée. La consommation au niveau source signifie que les modifications inter-packages se traduisent par un simple rechargement à chaud, pas par une boucle build-link-restart.
• La piste framework est découplée. Le versionnage, les changelogs et la publication passent par des changesets et des workflows de publication dédiés, à leur propre cadence, sans coordination avec les releases de l'application.

Le coût du dual mode est que la consommation interne peut masquer les pannes externes — ce qui est exactement la raison d'être de la porte publint et du smoke test externe.

Voir aussi

• Vue d'ensemble du framework
• ADR 0007 — Contrat port/adaptateur
• Runbook de basculement d'accès : docs/maintenance/npm-public-launch.md dans le monorepo