Skip to content

🎥 Make videos programmatically with React

Build: Gate npm release promotion on package availability

JonnyBurgerfbef27d5afb3
diff --git a/.agents/skills/release/SKILL.md b/.agents/skills/release/SKILL.md
index 135adbd74c..9d38931d80 100644
--- a/.agents/skills/release/SKILL.md
+++ b/.agents/skills/release/SKILL.md
@@ -17,16 +17,24 @@ description: Release a new Remotion version
- Run `npm view remotion version` to get the current version number
- Run `bun set-version.ts <version>`, where <version> is the current version plus 1. If the exit code is not 0, abort the entire release process immediately.
- Run `cd packages/example && sh runlambda.sh && cd ../..`. If this fails, abort the release.
-- Run `NPM_CONFIG_TOKEN=<token> bun run release` where <token> is the NPM token we just created
- - Ordinary publishing already triggers [npm's automatic malware scan](https://github.blog/changelog/2026-07-28-npm-publish-time-malware-scanning-and-dual-use-metadata/); no separate staging step is needed for the current direct-publish workflow. Availability commonly takes around five minutes, sometimes 15 minutes or longer. These times are not guarantees.
- - Verify every public package selected by `publish.ts` with `npm view <package>@<version> version --json`. A successful `bun publish --tolerate-republish` exit is not proof of availability: it can hide a `409 Cannot publish over previously staged version "<version>"`.
- - For missing versions or staging conflicts, check the [npm lifecycle status API](https://api-docs.npmjs.com/): `GET https://registry.npmjs.org/-/package/<encoded-package-name>/version/<version>/status`, authenticated with a token that has publish access. URL-encode scoped names, for example `@remotion%2Fwhisper-web`. Keep credentials out of logs.
- - If the status is `validating`, poll status and exact-version availability once per minute for up to one hour while continuing independent release work. Do not republish or restage the same version while scanning is pending. If it is still validating after this observation window, report it as an acceptable pending scan with its last observed status, not as available or guaranteed to become available.
- - If the version is awaiting maintainer approval, use `npm stage list <package> --json` and `npm stage view <stage-id> --json` to verify the package and version. [Wait for scanning to finish before approval](https://github.blog/changelog/2026-09-03-multiple-trusted-publishing-configurations-for-npm/), then run `npm stage approve <stage-id> --otp=<fresh-otp>` using the authenticated maintainer session and the 2FA instructions above. Waiting alone does not approve a staged version. Recheck exact-version availability after approval or a published status.
- - An empty stage list does not prove that scanning is pending or that a conflict will resolve itself. If the status API is unavailable, check `npm stage list` and the package's versions page on npmjs.com while logged in as a maintainer. A status API `403` can mean the endpoint is not enabled for this package; `404` can mean a missing version or insufficient access. Report blocked, rejected, manual-review, or unknown states and unresolved errors explicitly; do not classify them as acceptable scanning delays.
- - If npm explicitly returns `E_STAGE_REQUIRED`, follow [staged publishing](https://docs.npmjs.com/cli/v11/commands/npm-stage/): use `npm stage publish <tarball>` with the affected package's prepared release artifact, wait for scanning, then review and approve its stage as above. A staging 409 alone is not a reason to switch workflows or upload again.
- - In the release summary, distinguish verified available packages, confirmed pending scans, stages awaiting approval, and unresolved failures. Include the affected package and version for every pending or failed item. Other publish failures remain errors.
-- Once the new package versions needed by the templates are available, run `bun run publishtemplates` from the repository root to republish every template. If a required version is still pending, report template publishing as pending too. If any template fails to publish, stop the release workflow and report the failure.
+- Publish the public packages under a temporary npm dist-tag, then promote `latest` only after **every** package is installable. `validating` is [npm's automatic scan for ordinary publishes](https://github.blog/changelog/2026-07-28-npm-publish-time-malware-scanning-and-dual-use-metadata/), not a reason to use `npm stage`. Do not run `bun run release`: its current script publishes directly to `latest` and starts private publishing and Git pushes before the availability gate.
+ - From the repository root, after `set-version.ts`, run:
+
+ ```bash
+ releaseVersion=$(node -p "require('./packages/core/package.json').version")
+ releaseTag="remotion-release-$(printf '%s' "$releaseVersion" | tr . -)"
+ releaseManifest="/tmp/remotion-release-${releaseVersion}-packages.txt"
+ bun publish.ts --list > "$releaseManifest"
+ ```
+
+ The manifest is the exact package list to check and promote. Record each package's previous `latest` tag so a partial promotion can be rolled back.
+ - Check whether any package in the manifest is being published to npm for the first time. [Bun adds `latest` to a package's initial publish even with `--tag`](https://bun.com/docs/pm/cli/publish/). If there are new packages, stop before the bulk publish and plan their first publication separately; this flow cannot keep their first version off `latest`.
+ - Run `NPM_CONFIG_TOKEN=<token> bun publish.ts --tag="$releaseTag"` with the token created above. Bun still packs the packages and rewrites `workspace:` and `catalog:` dependencies. This tagged path does not tolerate republish errors. A successful upload is not proof that npm's scan is finished: check the manifest, exact package versions, and temporary tags. Do not upload the same version again while its scan is pending. If a publish attempt failed and the version is confirmed absent, resume that package alone with `bun publish.ts --tag="$releaseTag" --only=<package>` using the same token; never rerun the entire manifest blindly.
+ - For each package in the manifest, require `npm view <package>@<version> version --json` **and** a successful `npm pack <package>@<version> --pack-destination <temporary-directory>` before promotion. The pack check confirms the tarball can actually be fetched. Poll unresolved packages about once per minute; use the [npm lifecycle status API](https://api-docs.npmjs.com/) where available: `GET https://registry.npmjs.org/-/package/<encoded-package-name>/version/<version>/status`, authenticated with publish access. URL-encode scoped names, such as `@remotion%2Fwhisper-web`, and keep credentials out of logs. If a package remains `validating` after an hour, report the release as pending and leave every `latest` tag on the prior release. Blocked, rejected, manual-review, missing, and unknown states also stop promotion; investigate them rather than treating them as scanning delays.
+ - Once **all** packages are installable, use the release token through `NPM_CONFIG_TOKEN` to run `npm dist-tag add <package>@<version> latest` for every package in the manifest. This is one registry operation per package; npm has no atomic multi-package promotion. Verify that `npm view <package> dist-tags.latest` equals the release version for every package. If promotion fails partway, restore the recorded previous `latest` tags for packages already changed and report the incomplete release. After a successful promotion, remove the temporary tag from each package with `npm dist-tag rm <package> <releaseTag>` and verify the final tags.
+ - If npm explicitly returns `E_STAGE_REQUIRED`, direct publishing is unavailable for that package. Stop this release and assess a staged workflow separately; [staged approval requires a 2FA action per package](https://docs.npmjs.com/cli/v11/commands/npm-stage/). Do not silently mix a staged package into this direct-publish flow.
+- Only after all public `latest` tags are verified, run `bunx turbo run publishprivate --concurrency=1`, then `git push --tags` and `git push` from the repository root. If any step fails, stop and report the affected release state.
+- Run `bun run publishtemplates` from the repository root to republish every template after the public packages have been promoted. If any template fails to publish, stop the release workflow and report the failure.
- Generate a changelog in markdown and save it to `/tmp/release-<version>.md`:
- Run `git log v<previous_version>..v<new_version> --oneline` to get all commits
- Extract PR numbers from merge commits
diff --git a/publish.ts b/publish.ts
index 815c754477..24ff421774 100644
--- a/publish.ts
+++ b/publish.ts
@@ -13,6 +13,24 @@ import {FEATURED_TEMPLATES} from './packages/create-video/src/templates';
import {shouldReleasePackage} from './packages/studio-shared/src/release-package-policy';
const p = limit(4);
+const args = process.argv.slice(2);
+const listOnly = args.includes('--list');
+const tagArg = args.find((arg) => arg.startsWith('--tag='));
+const releaseTag = tagArg?.slice('--tag='.length) ?? null;
+const onlyArg = args.find((arg) => arg.startsWith('--only='));
+const onlyPackage = onlyArg?.slice('--only='.length) ?? null;
+
+if (
+ args.some((arg) => arg !== '--list' && arg !== tagArg && arg !== onlyArg) ||
+ (listOnly && (releaseTag !== null || onlyPackage !== null)) ||
+ (onlyPackage !== null && releaseTag === null) ||
+ releaseTag === '' ||
+ onlyPackage === ''
+) {
+ throw new Error(
+ 'Usage: bun publish.ts [--list | --tag=<dist-tag> [--only=<package>]]',
+ );
+}
const releaseVersion = JSON.parse(
readFileSync(
@@ -30,6 +48,7 @@ const dirs = readdirSync('packages')
);
const promises: Promise<unknown>[] = [];
+let foundOnlyPackage = false;
for (const dir of dirs) {
const localTemplates = FEATURED_TEMPLATES.map(
@@ -54,6 +73,14 @@ for (const dir of dirs) {
) {
continue;
}
+ if (onlyPackage !== null && packageJson.name !== onlyPackage) {
+ continue;
+ }
+ foundOnlyPackage = true;
+ if (listOnly) {
+ console.log(packageJson.name);
+ continue;
+ }
promises.push(
p(async () => {
@@ -66,7 +93,11 @@ for (const dir of dirs) {
}
try {
- await $`bun publish --tolerate-republish`.cwd(packagePath);
+ if (releaseTag === null) {
+ await $`bun publish --tolerate-republish`.cwd(packagePath);
+ } else {
+ await $`bun publish --tag=${releaseTag}`.cwd(packagePath);
+ }
} finally {
if (copiedLicense) {
unlinkSync(licensePath);
@@ -76,4 +107,8 @@ for (const dir of dirs) {
);
}
+if (onlyPackage !== null && !foundOnlyPackage) {
+ throw new Error(`No releasable package named ${onlyPackage}`);
+}
+
await Promise.all(promises);