npm-Pakete veröffentlichen

Die Einbettungs-Pakete erscheinen öffentlich auf npm unter dem Scope @pollyou:

Paket	Inhalt	Quelle
@pollyou/embed-core	Web Component <pollyou-survey>, Collector-Client, CDN-Build	frontend/packages/embed-core
@pollyou/react	React-Komponente und Hook	frontend/packages/react
@pollyou/vue	Vue-Komponente, Plugin und Composable	frontend/packages/vue
@pollyou/angular	Angular-Komponente	frontend/packages/angular
@pollyou/angularjs	AngularJS-Komponente	frontend/packages/angularjs

Versionen und Changelogs verwaltet Changesets, veröffentlicht wird über npm Staged Publishing. Veröffentlicht wird jedes Paket ohne "private": true; Dashboard, Docs und die übrigen internen Pakete sind privat und werden übersprungen. Neue öffentliche Pakete brauchen deshalb keine Änderung an .changeset/config.json.

Änderungen beschreiben

Wer ein öffentliches Paket ändert, legt im selben Commit ein Changeset an:

pnpm changeset          # Pakete und Art der Änderung (patch/minor/major) wählen, Text schreiben
pnpm changeset:status   # zeigt, welche Versionen beim nächsten Release entstehen

Das erzeugt eine Datei .changeset/<name>.md, die mit in den Pull Request gehört. Abhängige Pakete (z. B. @pollyou/react bei einer neuen @pollyou/embed-core-Version) erhöht Changesets automatisch mit.

Release auslösen

Die Bitbucket-Pipeline release-npm (Pipelines → Run pipeline → Branch main → custom: release-npm) läuft so:

1. Frontend-Prüfungen wie in jedem Build (ci/frontend.sh: Lint, Typecheck, Tests, Build, Paketinhalt).
2. Manuelle Freigabe des Schritts „Release npm packages“, danach ci/release-npm.sh:
   • liegen Changesets vor: changeset version erhöht die Versionen, schreibt die CHANGELOG.md der Pakete und aktualisiert den Lockfile; das Ergebnis wird als chore(release): version packages [skip ci] committet,
   • pnpm build und pnpm pack:check,
   • pnpm release:stage (ci/stage-npm.mjs) packt jedes öffentliche Paket, dessen Version weder auf npm liegt noch schon vorgemerkt ist, mit pnpm pack (das workspace:^ durch echte Versionsbereiche ersetzt) und merkt es mit npm stage publish bei npm vor (Staged Publishing); dazu entsteht ein Git-Tag wie @pollyou/react@1.1.0,
   • Commit und Tags werden auf den Branch gepusht.
3. Freigabe auf npm (siehe unten): Erst danach sind die Versionen installierbar.

Repository-Variable: NPM_TOKEN (gesichert) – ein npm Granular Access Token mit „Read and write (stage only)“ für den Scope @pollyou. Das Token landet nur in einer temporären .npmrc außerhalb des Repositorys. Ein Stage-only-Token kann allein nichts veröffentlichen; npm lehnt direktes npm publish damit ab (bei neuen Paketen als E404 beim PUT).

Ohne neue Changesets merkt die Pipeline nur Versionen vor, die noch fehlen – beim allerersten Lauf also die aktuellen Versionen aller Pakete. Ein erneuter Lauf überspringt bereits vorgemerkte Versionen.

Vorgemerkte Versionen freigeben

Ein Maintainer der Organisation @pollyou mit aktivierter Zwei-Faktor-Authentifizierung gibt jede vorgemerkte Version frei:

• auf npmjs.com im Tab Staged Packages → Approve (mit 2FA-Bestätigung), oder
• per CLI: npm stage list zeigt die vorgemerkten Versionen mit ihrer <stage-id>, npm stage approve <stage-id> gibt frei (npm stage reject <stage-id> verwirft).

Reihenfolge: zuerst @pollyou/embed-core, dann die Framework-Pakete, die davon abhängen – das Pipeline-Log listet die Pakete am Ende in dieser Reihenfolge. Ein neues Paket zeigt bis zur ersten Freigabe nur die öffentliche Platzhalter-Version 0.0.0-stage.

Probelauf

DRY_RUN=1 ./ci/release-npm.sh     # versioniert lokal, baut, prüft und zeigt, was vorgemerkt würde – ohne Commit, Staging und Push
pnpm release:stage --dry-run      # nur: welche Pakete würden vorgemerkt?

Änderungen eines Probelaufs (Versionen, Changelogs) danach mit git checkout . verwerfen.

Paketinhalt

pnpm pack:check (ci/pack-check.mjs, Teil von ci/frontend.sh) packt jedes öffentliche Paket mit pnpm pack --dry-run und prüft, dass

• alle in main, module, types und exports genannten Dateien enthalten sind (bei publishConfig.exports bzw. publishConfig.directory die veröffentlichte Fassung),
• package.json und README.md dabei sind,
• keine Quelltexte, Tests, Stories oder Build-Konfigurationen mitkommen,
• publishConfig.access public ist und eine Lizenz angegeben ist.

Besonderheiten:

• @pollyou/embed-core exportiert im Workspace seine TypeScript-Quellen (Dashboard und Framework-Pakete nutzen sie direkt). Erst beim Veröffentlichen gelten über publishConfig die Einträge dist/esm/index.js (ESM, Lit als Abhängigkeit) und dist/types/index.d.ts; die Typen der internen Pakete @pollyou/themes und @pollyou/survey-schema sind dort eingebettet (tsdown.types.config.ts), deren Code steckt bereits im ESM-Build. Zusätzlich enthält das Paket den CDN-Build (dist/cdn), sodass embed.js auch über unpkg/jsDelivr erreichbar ist.
• @pollyou/react und @pollyou/vue bauen mit tsdown ESM, CommonJS und Typen (.d.ts/.d.cts); @pollyou/react behält die Direktive 'use client'.
• @pollyou/angular wird mit ng-packagr nach dist gebaut und von dort veröffentlicht (publishConfig.directory).