Publishing
npm packages
@screenplay.space/knobs and @screenplay.space/state are published by two
manual workflows, publish-knobs.yml and publish-state.yml. Run one from
the Actions tab with a bump (patch, minor, major, prerelease, an
exact version, or none to publish what package.json already says) and an
npm dist-tag. Each run:
- checks that
main’s version matches what’s on npm, - bumps the version on a
release/screenplay-<package>-v<version>branch and pushes it, - pushes the
screenplay-<package>-v<version>tag, - publishes to npm through Trusted Publishing (no npm token), and
- opens a “Release …” pull request. Merge it so
maincatches up.
Agents don’t run these workflows: the maintainer publishes. A pull request that changes a package doesn’t bump its version; publish after it merges. Publishing can’t be undone, so wait until the changes you want in a release have all merged.
Recovering from a failed run
The release branch and tag are pushed before npm publish. When a run
fails after that, the branch and tag stay behind, and the next run with the
same bump collides with them. Before you run again, check npm and the
repository:
- If the version isn’t on npm, delete the leftover
release/…branch and tag, then run again with the same bump. - Or leave them and run with an explicit, higher version.
If the drift check fails, main’s package.json is behind npm: merge the
outstanding release pull request first.
Desktop app
The desktop app is released from a Mac with one command; see Releasing the desktop app.
Preview deploys
Production (main) always deploys. Preview deploys of the app, docs and
homepage are opt-in, because they cost build credits.
scripts/vercel-ignore-build.sh decides, and a pull request opts in with:
- the
previewlabel (every site) orpreview:app,preview:docsorpreview:homepage(one site). Push, or redeploy, after adding the label. [preview]or[preview:<site>]in a commit’s subject line. The body doesn’t count. Keep the bracketed token out of a subject unless you want a preview.
A skipped deploy shows “Canceled by Ignored Build Step” on the pull request.
The orphan branches claude/pr-screenshots and claude/design-archive hold
images, not app code, so each carries a vercel.json with
"git": { "deploymentEnabled": false } at its root and in each project’s
folder (apps/app, apps/docs, apps/homepage). Vercel reads it from the
commit it deploys, so no setting on main can turn these builds off. Keep the
files, and add them first if either branch is ever recreated.