Releasing BCP Framework

The source repository is a private npm workspace package for development. Release artifacts are staged separately so monorepo-only paths cannot accidentally become the published package contract.

BCP Framework and create-bcp-app are prepared for public release under the MIT License. Normal build and test tooling never performs a real npm publish automatically. The dedicated release publish command requires explicit confirmation and a matching Git tag.

The selected public npm identities are:

@chidchanun/bcp
create-bcp-app

Application source continues importing from bcp. create-bcp-app stores the scoped framework package behind the dependency key bcp using an npm alias.

1. Synchronize versions

Use the version helper instead of editing package metadata manually:

npm run version:set -- 0.1.10

It synchronizes the release version across:

package.json
packages/client/package.json
create-bcp-app/package.json
package-lock.json

Review CHANGELOG.md after changing the version. The BCP CLI reads the framework version from package metadata instead of a duplicated hard-coded constant.

2. Run the normal release gate

npm run release:check

This runs type checking, the complete unit/integration/E2E/package test suite, then verifies:

• synchronized semver metadata
• required documentation
• MIT license metadata and license files
• staged public package exports and executable metadata
• public npm access configuration
• exact v<version> matching when the check runs from a Git tag

The package smoke test performs clean installs from packed tarballs and verifies that npm actually creates the bcp and create-bcp-app executables in node_modules/.bin.

3. Verify npm package names and ownership

Authenticate to npm before publishing:

npm login
npm whoami

Then run:

npm run release:name-check

The default RC package names are locked by scripts/release-env.mjs to:

@chidchanun/bcp
create-bcp-app

The check queries both package names. If a package is not present in the registry, the name is treated as currently available. If it already exists, the current npm account must be listed as an owner or the check fails.

The defaults may still be overridden deliberately for a future rename:

BCP_PACKAGE_NAME=@another-scope/bcp npm run release:name-check

PowerShell:

$env:BCP_PACKAGE_NAME="@another-scope/bcp"
npm run release:name-check

The Release Check workflow also accepts the optional repository variables:

BCP_PACKAGE_NAME
BCP_CREATE_PACKAGE_NAME

When those variables are unset or empty, the locked defaults above are used. Package-name availability can change at any time, so treat this check as a point-in-time release gate rather than a permanent reservation.

4. Verify the release version against npm

Run:

npm run release:version-check

This separately checks the exact local release version against both selected npm package names.

The gate fails when:

• <package>@<local-version> already exists and therefore cannot be republished
• the local version is older than or equal to the registry's current latest version

A published npm version is immutable. If a packaging defect is discovered after publication, increment the patch version instead of trying to replace the existing version.

5. Run npm publish dry-run and clean-install smoke

npm run release:dry-run

This performs npm publish --dry-run for both staged packages, packs fresh tarballs, installs the framework tarball into a temporary clean project, verifies the installed bcp executable, installs the create-bcp-app tarball separately, and verifies its generated executable.

No package is uploaded to the npm registry.

Artifacts are written to:

.package/artifacts/

6. Run the complete Release Candidate gate

For the final local RC check:

npm run rc:check

This is equivalent to:

npm run release:check
npm run release:name-check
npm run release:version-check
npm run release:dry-run

Run this immediately before creating the release tag.

7. Inspect package contents

Review:

.package/bcp/package.json
.package/bcp/LICENSE
.package/create-bcp-app/package.json
.package/artifacts/*.tgz

Useful manual checks:

npm pack --dry-run .package/bcp
npm pack --dry-run .package/create-bcp-app

The framework package is published as:

@chidchanun/bcp

but exposes application import paths through the npm alias key:

bcp
bcp/island
bcp/cache
bcp/config
bcp/middleware

and the executable:

bcp

A newly generated application's package.json pins the selected framework release exactly so a later plain package-manager install cannot silently move BCP to a different release:

{
  "scripts": {
    "update": "bcp update"
  },
  "dependencies": {
    "bcp": "npm:@chidchanun/[email protected]"
  }
}

The explicit updater is responsible for resolving and installing later framework releases.

8. Create the release tag

Only after npm run rc:check passes and CHANGELOG.md is ready:

git status
git tag -a v0.1.10 -m "BCP Framework v0.1.10"
git push origin v0.1.10

Use the actual version from package.json in the tag.

The GitHub Release Check workflow validates a v* tag, rechecks the npm target version, and uploads the npm tarballs as workflow artifacts. It does not publish them.

9. Guarded publish

After the tag workflow artifacts have been reviewed, publish from an authenticated local npm session with:

npm run release:publish:yes

This explicit script is preferred over forwarding --yes through npm run, because npm CLI argument forwarding can vary by npm/platform version.

The command refuses to publish unless all of these conditions are true:

• explicit publish confirmation is present
• the git working tree is clean
• HEAD has the exact tag v<package-version>
• npm authentication succeeds
• the RC checks succeed again
• staged package names and versions match the selected release
• the target version has not already been accepted by npm

Stable BCP releases use this npm dist-tag by default, including stable 0.x releases:

latest

Use BCP_DIST_TAG only when intentionally publishing a separate channel such as next or beta:

BCP_DIST_TAG=beta npm run release:publish:yes

PowerShell example:

$env:BCP_DIST_TAG="beta"
npm run release:publish:yes

The framework publishes first. After npm publish succeeds, the release script accepts either normal version visibility or the selected dist-tag pointing at the new version. This prevents npm registry/security-processing delays from being misclassified as a failed publish.

Using latest for stable releases is also part of the updater contract: bcp update resolves @chidchanun/bcp@latest by default.

10. Recover from a partial publish

If the framework package was accepted by npm but publishing create-bcp-app failed, fix the external issue without changing that release commit or tag, then use:

npm run release:resume

Resume mode intentionally does not run release:version-check or npm publish --dry-run for the already-published version. It still runs the complete local release checks and package smoke tests, verifies package ownership, skips package versions already accepted by npm, and attempts only the missing package.

Do not use resume mode to overwrite or replace an existing npm version; npm versions are immutable.

11. Install or update the stable release

The recommended new-project path is:

npx create-bcp-app@latest my-app

A generated application keeps the documented bcp import name through an npm alias and pins the selected framework version exactly.

For an existing project already on an updater-capable release:

npm run update

For a project on BCP 0.1.9 or older, bootstrap the updater once with:

npx @chidchanun/bcp@latest update

A manual install that preserves the bcp import name is:

npm install bcp@npm:@chidchanun/bcp@latest react react-dom

Application code then continues using:

import {
    Link,
} from "bcp";

The scoped package can also be installed directly as @chidchanun/bcp@latest, but applications using the framework's documented bcp import path should prefer the alias form above.

12. Trusted publishing

For subsequent releases, prefer npm Trusted Publishing with GitHub Actions instead of a long-lived write token. npm supports GitHub Actions OIDC publishing and recommends trusted publishing for CI-based releases.

After the npm package settings are available, configure the repository/workflow as a trusted publisher and move the real publish action into the guarded GitHub release workflow.

License

BCP Framework and create-bcp-app use the MIT License. See LICENSE and create-bcp-app/LICENSE.