@shelf/ci-utils

Install

$ npx -p=@shelf/ci-utils <cmd> [args...]

Usage

Get latest git tag version

Set the RELEASE_VERSION to .env file in your project.

On master, uses the latest discovered Git tag, including its v prefix, or latest when no tag exists. Other branches use latest-<branch>.

npx -p=@shelf/ci-utils get-git-version

Validate a release before merging

Checks that a release/vX.Y.Z or hotfix/vX.Y.Z branch has a matching GitHub release. A draft without a Git tag must target the current branch or commit. An existing tag must point to the exact checkout HEAD. The version must be newer than the other remote release tags. Exits with code 1 when validation fails.

npx -p=@shelf/ci-utils validate-release

# Explicit branch for a detached checkout
npx -p=@shelf/ci-utils validate-release --branch release/v1.2.3

# JSON output
npx -p=@shelf/ci-utils validate-release --json

Run inside the repository with Git credentials and GH_API_TOKEN from the CircleCI github context. GH_TOKEN and GITHUB_TOKEN are also supported. The token must be able to read draft releases. Repository, CircleCI branch, and SHA are detected automatically; --remote overrides origin. No token or repository argument is needed. Require this check before merging and rerun failed jobs after fixing the release. Publishing a draft creates its tag; a draft does not need one to pass.

Get AWS SSM parameter

Set the SSM parameter name to .env file in your project. By default, It would append the ENVIRONMENT to the parameter name.

You can override it by passing the whole parameter name in /<env>/<param-name> format (allowed envs: prod, staging).

npx -p=@shelf/ci-utils get-ssm-param <env-name> <param-name>

# Given: the /prod/s3_bucket parameter in SSM equals to 'my-prod-bucket' & ENVIRONMENT=prod
npx -p=@shelf/ci-utils get-ssm-param MY_PARAM s3_bucket # /prod/s3_bucket MY_PARAM=my-prod-bucket in .env
npx -p=@shelf/ci-utils get-ssm-param MY_PARAM /staging/s3_bucket # /staging/s3_bucket MY_PARAM=stage_bucket in .env

Get multiple AWS SSM parameters (batch)

Retrieves multiple SSM parameters in a single AWS API call and writes them to .env file. Uses the same parameter name resolution logic as the single parameter version.

npx -p=@shelf/ci-utils get-ssm-params ENV_KEY1=param1 ENV_KEY2=param2 [ENV_KEY3=param3 ...]

# Examples:
npx -p=@shelf/ci-utils get-ssm-params MY_S3_BUCKET=s3_bucket DATABASE_HOST=db_host
npx -p=@shelf/ci-utils get-ssm-params API_KEY=/staging/api_key DB_PASSWORD=db_pass

Set Next.js base path

Sets the NEXT_BASE_PATH to .env file in your project based on the CIRCLE_BRANCH value. For main branches (master, develop, main) it will ignore the circle branch. The ci branch is normalized, see the nextjs-base-path.test.js file for details.

npx -p=@shelf/ci-utils set-nextjs-base-path <custom-base-path?>

# Given: CIRCLE_BRANCH=master
npx -p=@shelf/ci-utils set-nextjs-base-path # NEXT_BASE_PATH=
npx -p=@shelf/ci-utils set-nextjs-base-path read # NEXT_BASE_PATH=/read


# Given: CIRCLE_BRANCH=feature/ADMINAPP-123-feature-description
npx -p=@shelf/ci-utils set-nextjs-base-path # NEXT_BASE_PATH=/ADMINAPP-123
npx -p=@shelf/ci-utils set-nextjs-base-path custom-path # NEXT_BASE_PATH=/custom-path-ADMINAPP-123

# Given: CIRCLE_BRANCH=release/v1.0.0
npx -p=@shelf/ci-utils set-nextjs-base-path # NEXT_BASE_PATH=/v1.0.0
npx -p=@shelf/ci-utils set-nextjs-base-path custom-path # NEXT_BASE_PATH=/custom-path-v1.0.0

# Later it could be used in circleci/config.yml and next config to allow per-branch deployment
- run: npx -p=@shelf/ci-utils set-nextjs-base-path read
- run: pnpm build
- run:
    name: deploy to s3
    command: |
      source .env
      aws s3 sync . "s3://$AWS_S3_BUCKET_NAME$NEXT_BASE_PATH"

// next.config.js

const basePath = process.env.NEXT_BASE_PATH ?? '/read'; //default value for local development
export default {
  basePath,
};

Generate deployment version file

Creates dist/version.json with the release version, CircleCI commit SHA, and build timestamp. The file is used by deployed apps to detect a new version.

The command requires RELEASE_VERSION and CIRCLE_SHA1 environment variables. Pass a different output directory when the app does not use dist.

# Run after the app build
npx -p=@shelf/ci-utils generate-version-file

# Custom output directory
npx -p=@shelf/ci-utils generate-version-file build

The generated file has this shape:

{
  "version": "v1.2.3",
  "commit": "abc123",
  "builtAt": "2026-07-13T10:20:30.000Z"
}

Publish

git checkout master
pnpm version patch # or minor / major
pnpm publish --access public
git push origin master --tags

License

MIT © Shelf