Release checklist

Runway UI is a JavaScript/TypeScript library; it does not need a Rust crate. A main-branch push, a Pages deployment and an npm package publication are separate outcomes. Publishing a package or creating a tag/release requires an explicit request. The tag-only npm workflow below is separate from main/Pages deployment.

Prepare and validate

Use the Bun version in .bun-version and the committed bun.lock:

bun install --frozen-lockfile
bun check
bun run test-behaviors
bun run build
bun run build-site
bun run check-docs
bun pm pack --dry-run

bun check is the project script: source/boundary/format checks, generated public declarations, native type checks and the dependency-map check. Bun does not have a built-in general-purpose lint command. test-behaviors runs the TypeScript test suite, including boundary, dialog and package-export contracts. build-site builds the library, Storybook and static documentation; it does not deploy. Do not run the library and Storybook builds concurrently in one checkout: Storybook consumes generated library assets.

For a requested versioned release, choose the version using the compatibility policy, update package.json and the lockfile consistently, and record changes and migration instructions in CHANGELOG.md. Preserve public exports, the zero-runtime-dependency CSS and the required React, Base UI and TanStack Charts peers. Review relevant browser, keyboard, forced-color and reduced-motion behavior; passing tooling alone does not establish browser support.

Commit source changes together with generated styles/icons.css and dist/runway-ui.css, then run:

bun run check-generated

This compares rebuilt CSS against HEAD, so intended generated changes must be committed first. Authored modules are TypeScript/TSX. Generated JavaScript and public declarations under dist/behaviors and dist/react are rebuilt, not hand-edited; type and package-export tests check those outputs.

Main and Pages

Push only the reviewed, tested changes and verify the exact commit's Package and GitHub Pages workflows. Before publication, run bun run build-site, bun run check-docs and bun run check-pages. The browser gate serves the build under the real project prefix and checks the public entry points and recipes. After deployment, run bun run check-pages https://kahwee.github.io/runway-ui/ to verify the live artifact. See Storybook checks. A successful Pages deployment updates the workshop, docs and Storybook, not the npm registry. Verify the relevant live behavior and report the commit and workflow links without claiming package publication.

Automatic npm publication

The package is @kahwee/runway-ui from kahwee/runway-ui. The workflow file is .github/workflows/publish.yml, with no GitHub environment. Its publishing job alone requests OIDC id-token: write; npm's trusted-publisher binding must match owner kahwee, repository runway-ui, and filename publish.yml exactly. An account owner configures that binding separately. No npm token, local login, 2FA change or package-manager credential is required by the workflow.

Ordinary main pushes and pull requests validate but never publish. A vX.Y.Z tag must match package.json exactly and point to source reachable from main. Stable versions publish to latest; prereleases such as v0.6.0-beta.2 publish to next. The workflow explicitly selects the tag rather than relying on publishConfig.tag. It does not create tags, bump versions, promote older versions or retry publication. An existing registry version stops the job.

Before requesting a version tag, update the version and lockfile consistently, record migration notes in the changelog, and merge the tested source to main. Tag publication remains a deliberate release action, not incidental cleanup. Package validation runs source/type/behavior checks and verifies the archive's manifest, license, CSS and exported files. Five independent browser matrix jobs cover 320, 390, 768, 1366 and 1440px using Chrome already installed on GitHub's Ubuntu runner. The 1440px shard also checks the Storybook manager/Controls flow. All six jobs start independently, and publication waits for every one to succeed. They do not reinstall peer libraries into a throwaway consumer or retest upstream React/Base UI/TanStack interoperability. Only the verified archive passes to the publishing job; its checksum is verified before publishing. Registry version, archive integrity and the intended dist-tag are checked afterward. Readback starts immediately and waits only when registry data is not ready; it never repeats the upload.

The package already exists; no bootstrap publication is needed. Registry verification on 2026-10-28 found latest at 0.7.0 and next at 0.6.0-beta.1. The 0.7.0 publication predates this workflow's activation; registry ownership or release email alone does not establish its publishing method or source/archive provenance. Activating the workflow does not republish an existing version or change either dist-tag.

A new npm trusted-publisher binding remains pending validation until its first successful publication. npm expires an unused new binding after two days; do not promise indefinite readiness or create an arbitrary version to validate it. Coordinate the binding with a legitimate, authorized release. See npm's trusted-publisher documentation.

The prepack hook rebuilds for manual packing. This workflow explicitly builds and validates before packing without lifecycle scripts; publication also skips scripts so the tested bytes stay unchanged. Generated runtime JavaScript and public declarations must be present in the archive. Source archive consumers must install and run bun run build before using runtime exports.

Validation timing

The supplied v1.2.0 validation job took about 1m 47s: browser installation consumed 37s and serial viewport checks consumed 39s. The release pipeline now separates package checks from five parallel viewport jobs and uses the runner's existing Chrome through PLAYWRIGHT_CHROMIUM_CHANNEL=chrome. Browser download and system package installation are removed from the critical path. Pages and PR browser checks use the same installed channel.

RUNWAY_CHECK_WIDTH selects one supported width for a shard; unset, check-pages retains all five widths. The Storybook manager checks run with the 1440px shard, so splitting the jobs preserves the combined coverage. Record actual workflow job timings after pushing; do not treat a proposed time reduction as measured.

The publish command itself took 5s in the supplied run. Its later 164s registry readback was a separate propagation wait after the upload had succeeded. A faster validation path does not make an unpropagated registry response valid. Package version, integrity and dist-tag checks remain mandatory.