form-schema-runtime

GitHub Release publishing, npm Trusted Publishing/OIDC, and verification.

Documentation pages
On this page
  1. Published Versions And Stable Release
  2. npm README Lifecycle
  3. Release Philosophy
  4. Why GitHub Release Driven
  5. One-Time npm Setup
  6. GitHub Setup
  7. Why npm Trusted Publishing/OIDC
  8. Version and Tag Convention
  9. Preparing a Release
  10. Creating a GitHub Release
  11. What the Release Workflow Does
  12. Package Contents
  13. Verifying a Published Package
  14. If Publishing Fails
  15. What Not To Commit
  16. CI vs Release
  17. Official References

Release Process

This project publishes npm packages from GitHub Releases. Publishing is intentional only when a GitHub Release is published for a tag that exactly matches package.json.

Published Versions And Stable Release

The published npm history is:

  • npm package: form-schema-runtime
  • 0.1.0 was published manually.
  • 0.1.1 was published through the GitHub Release workflow with npm Trusted Publishing/OIDC.
  • 1.0.0 is the first stable npm release.
  • 1.0.1 is the current published npm release.

npm package versions are immutable. Re-running an existing release workflow cannot overwrite an already published version such as form-schema-runtime@0.1.0 or form-schema-runtime@0.1.1; npm will reject the publish with an error that the version was previously published.

Do not rerun an existing release expecting npm to overwrite the package. Do not unpublish published versions, delete GitHub Releases, force-push tags, or create replacement tags unless explicitly requested by the repository owner.

The first stable release used the package version and matching GitHub Release tag:

  • package version: 1.0.0
  • GitHub Release tag: v1.0.0

Every release must keep package.json and the GitHub Release tag aligned: package version <version> requires tag v<version>. Future versions must be published through GitHub Release + npm Trusted Publishing/OIDC. The release workflow checks npm before publishing and fails early if the package version already exists.

npm README Lifecycle

npm renders the root README.md contained in the published package. The package page README changes only when a new package version is published; changing README.md on GitHub does not update an existing npm version.

Treat npm-facing README corrections as package changes. If a correction must appear on npmjs.com, prepare a new semantic version, keep the new version and GitHub Release tag aligned, and publish it through the normal release workflow. Use absolute public URLs in the root README because repository docs and framework example sources are intentionally excluded from the npm tarball.

Release Philosophy

  • Keep CI and release publishing separate.
  • Use GitHub Releases as the human approval gate.
  • Publish only package files needed by consumers.
  • Verify package consumption before publishing.
  • Prefer npm Trusted Publishing/OIDC over long-lived npm publish tokens.
  • Do not commit generated build output, coverage reports, TypeDoc output, Playwright reports, temporary consumer projects, or npm package tarballs.

Why GitHub Release Driven

The release workflow runs on:

release:
  types: [published]

This means publishing a GitHub Release is the explicit release action. Pull requests and normal pushes verify the project through CI, but they do not publish to npm.

The GitHub Release is the approval trigger and source tag; the package itself is published to the public npm registry at npmjs.com, not to GitHub Packages.

GitHub can generate release notes from merged pull requests and contributors. The repository also includes .github/release.yml to keep generated notes grouped into Features, Fixes, Documentation, Maintenance, Dependencies, Tests, and Other Changes.

Expected PR labels:

  • feature or enhancement
  • bug or fix
  • documentation or docs
  • maintenance or chore
  • dependencies
  • tests or test
  • ignore-for-release to omit a PR from generated notes

One-Time npm Setup

The first manual publication is complete. Keep this setup accurate for future automated releases:

  1. Create or log in to the npm account that will own the package.
  2. Enable 2FA as appropriate for the account and organization.
  3. Verify that form-schema-runtime is available or owned by the intended maintainer.
  4. Configure npm Trusted Publisher for the package.
  5. Configure provider: GitHub Actions.
  6. Configure GitHub owner/repository: DanieleMasone/form-schema-runtime.
  7. Configure workflow filename: release.yml.
  8. Configure package name: form-schema-runtime.
  9. Leave environment blank unless the workflow later adds an npm release environment.
  10. Allow action: npm publish.

All npm Trusted Publisher fields are case-sensitive. The package repository.url in package.json must exactly match the GitHub repository:

"repository": {
  "type": "git",
  "url": "git+https://github.com/DanieleMasone/form-schema-runtime.git"
}

GitHub Setup

Before publishing:

  • Confirm GitHub Actions are enabled for the repository.
  • Confirm the release workflow has contents: read and id-token: write permissions.
  • Confirm repository Pages deployment is handled by CI.
  • Confirm the release creator has permission to create GitHub Releases and tags.
  • Confirm main is green before drafting the release.

Why npm Trusted Publishing/OIDC

The release workflow uses npm Trusted Publishing through GitHub Actions OIDC.

Benefits:

  • no persistent NPM_TOKEN stored in GitHub secrets
  • short-lived publish credentials minted for the matching workflow
  • automatic provenance for public packages from public repositories
  • fewer token rotation and exposure risks

The workflow intentionally runs:

npm publish --access public

It does not pass --provenance because npm Trusted Publishing from GitHub Actions automatically generates provenance attestations when the package and repository are public.

Version and Tag Convention

Use semantic versions in package.json and matching Git tags:

package.json version: 1.0.0
GitHub Release tag: v1.0.0

The release workflow rejects tags that do not match v<semver> or do not match the package version. It also queries npm and rejects versions that are already published.

Examples:

  • package.json version 1.0.0 requires GitHub tag v1.0.0.
  • package.json version 1.0.1 requires GitHub tag v1.0.1.

Preparing a Release

  1. Make sure main is green in CI.
  2. Confirm package.json version is the intended release version.
  3. Update docs if public behavior changed.
  4. Run local verification:
npm ci
npm run typecheck
npm run lint
npm test
npm run test:coverage
npm run build
npm run test:site-docs
npm run build:examples
npm run test:examples
npm run test:consumer
npm run test:e2e
npm run verify:release -- --tag v<package-version> --pack
npm run verify:release -- --tag v<package-version> --check-published
npm pack --dry-run
  1. Commit the source changes.
  2. Do not commit dist/, dist-demo/, coverage/, playwright-report/, test-results/, temporary consumer projects, or *.tgz.
  3. Push to main.

Creating a GitHub Release

  1. Open GitHub Releases.
  2. Draft a new release.
  3. Create or select tag v<package-version>, for example v1.0.0.
  4. Set the release title to the tag or a concise release title.
  5. Use GitHub's generated release notes.
  6. Review the generated notes.
  7. Publish the release.

Publishing the release starts .github/workflows/release.yml.

What the Release Workflow Does

The workflow:

  1. checks out the repository
  2. sets up Node 24 and the npm registry
  3. installs with npm ci
  4. verifies tag/version/package metadata
  5. runs typecheck
  6. runs lint
  7. runs unit tests
  8. builds only the npm package with npm run build:lib
  9. installs the already-built package in a temporary consumer project
  10. verifies ESM import, CSS export, TypeScript declarations, and IIFE availability
  11. verifies package contents with npm pack --dry-run --json
  12. runs npm pack --dry-run
  13. checks that the package version is not already published on npm
  14. publishes to npm with Trusted Publishing/OIDC

The release workflow deliberately does not build the demo, generated HTML docs, TypeDoc site, coverage site, framework examples, or run Playwright. CI verifies and deploys those Pages assets; they are not part of the npm tarball.

Package Contents

The npm package intentionally includes only:

  • dist/
  • README.md
  • LICENSE
  • package.json because npm always includes it

It must not include source files, tests, demo, generated Pages output, coverage, Playwright reports, temporary consumer projects, or package tarballs.

Verifying a Published Package

After a successful release:

npm view form-schema-runtime version
npm view form-schema-runtime dist-tags
npm view form-schema-runtime readme
npm view form-schema-runtime repository homepage bugs
npm view form-schema-runtime --json

Install it in a throwaway project and verify:

import { createForm, type FormSchema } from "form-schema-runtime";
import "form-schema-runtime/styles.css";

Also verify:

  • TypeScript resolves FormSchema.
  • The package can be imported as ESM.
  • The CSS export resolves.
  • The IIFE build exists for direct browser usage.
  • npm provenance is present when available.

For direct browser usage, the IIFE build exposes:

FormSchemaRuntime

If Publishing Fails

  • If the workflow fails before npm publish because of a transient service or runner problem, it can be rerun while that version remains unpublished.
  • If source changes are required after the release tag was created, prepare a new version and matching tag instead of moving or force-pushing the existing tag.
  • If the workflow fails because the version is already published, bump package.json to a new version and create a new matching GitHub Release tag.
  • Do not rerun the same release expecting npm to overwrite an existing version.
  • If npm authentication fails, verify the npm Trusted Publisher package name, owner/repository, workflow filename, allowed action, and optional environment.
  • If publish succeeds with a bad package, deprecate the bad version and publish a corrected patch version.
  • Do not overwrite or reuse published npm versions. npm versions are immutable after publication.

What Not To Commit

Never commit:

  • generated npm package tarballs
  • dist/
  • dist-demo/
  • coverage/
  • generated TypeDoc output
  • Playwright reports
  • temporary consumer projects
  • local npm caches

CI vs Release

CI runs on pushes and pull requests. It verifies install, typecheck, lint, unit tests, coverage, the complete Pages build, generated HTML docs, framework example builds, framework example checks, consumer package smoke testing, Playwright, and Pages deployment on main.

Release runs only when a GitHub Release is published. It repeats package-focused quality checks, builds only the distributable library, runs the consumer smoke test, verifies package contents, and publishes to npm. Pages generation remains in CI.

Official References