badges-ts

Documentation

Overview

@jonloucks/badges-ts is a CLI-first tool for generating project SVG badges and version artifacts.

Primary workflows:

Installation

npm install @jonloucks/badges-ts

or run directly:

npx badges-ts <command>

Command Reference

discover

Discovers project information from package.json and logs name/version.

badges-ts discover

generate

Generates badges using project metadata, coverage data, and template values.

badges-ts generate

Generation includes:

Coverage is resolved from the first available source:

  1. KIT_CODE_COVERAGE_PERCENT
  2. Coverage summary JSON (KIT_COVERAGE_SUMMARY_PATH)
  3. LCOV report HTML index (KIT_LCOV_REPORT_INDEX_PATH)

apply-version

Creates/updates src/version.ts and creates release notes from template for the current package version.

badges-ts apply-version

Behavior notes:

version

Prints CLI version.

badges-ts version

help

Prints usage information.

badges-ts help

Flags

These flags are supported by command context handling:

Configuration Sources

badges-ts can read configuration from:

Configuration Profiles

1) Default local project profile

Use defaults with explicit color tuning:

{
	"kit.badges.folder": "badges",
	"kit.template.badge.path": "src/data/badge-template.svg.dat",
	"kit.100.percent.color": "#4bc124",
	"kit.above.90.percent.color": "#377526",
	"kit.below.60.percent.color": "darkred",
	"kit.0.percent.color": "#ff0000"
}

2) Monorepo package profile

Run from repo root, but target a package directory:

{
	"kit.project.folder": "packages/my-library",
	"kit.package.json.path": "package.json",
	"kit.coverage.summary.path": "coverage/coverage-summary.json",
	"kit.lcov.report.index.path": "coverage/lcov-report/index.html",
	"kit.badges.folder": "../../badges",
	"kit.npm.badge.path": "my-library-npm.svg",
	"kit.coverage.summary.badge.path": "my-library-coverage.svg",
	"kit.typedoc.badge.path": "my-library-typedoc.svg"
}

3) CI-only profile

Use explicit CI paths and injected coverage percent:

{
	"kit.badges.folder": "artifacts/badges",
	"kit.template.badge.path": "src/data/badge-template.svg.dat",
	"kit.coverage.summary.badge.path": "coverage-summary.svg",
	"kit.npm.badge.path": "npm.svg",
	"kit.typedoc.badge.path": "typedoc.svg"
}

Example CI command:

KIT_CODE_COVERAGE_PERCENT=94.6 npx badges-ts generate --verbose

4) gh-pages publishing profile

Write badges to a branch/worktree folder used for site publishing:

{
	"kit.project.folder": ".",
	"kit.badges.folder": "gh-pages/badges",
	"kit.coverage.summary.badge.path": "main-coverage.svg",
	"kit.npm.badge.path": "main-npm.svg",
	"kit.typedoc.badge.path": "main-typedoc.svg",
	"kit.coverage.summary.path": "coverage/coverage-summary.json",
	"kit.lcov.report.index.path": "coverage/lcov-report/index.html"
}

If you publish coverage and typedoc to gh-pages, keep badge filenames stable (for example main-*.svg) so README links do not need to change per run.

Example GitHub Actions step sequence:

jobs:
  badges:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout main
        uses: actions/checkout@v4
        with:
          path: main-project

      - name: Checkout gh-pages
        uses: actions/checkout@v4
        with:
          ref: gh-pages
          path: gh-pages

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "24"

      - name: Install and generate badges
        working-directory: main-project
        run: |
          npm ci
          KIT_BADGES_FOLDER="$/gh-pages/badges" npm run badges

      - name: Commit gh-pages badge updates
        uses: EndBug/add-and-commit@v9
        with:
          default_author: github_actions
          message: "Update badges"
          add: "badges/*.svg"
          cwd: gh-pages

Artifact-based variant (recommended for privileged publish flows):

# Workflow A: unprivileged build/generate (aligned with main-push)
name: main-push
on:
	push:
		branches: [main]

permissions:
	contents: read

jobs:
	build-badges:
		runs-on: ubuntu-latest
		steps:
			- uses: actions/checkout@v4

			- uses: actions/setup-node@v4
				with:
					node-version: "24"

			- run: npm ci
			- run: npm run badges

			- uses: actions/upload-artifact@v4
				with:
					name: publish-badges
					path: "*.svg"

# Workflow B: privileged publisher (aligned with main-push-publish)
name: main-push-publish
on:
	workflow_run:
		workflows: [main-push]
		types: [completed]

permissions:
	actions: read
	contents: write

jobs:
	publish:
		if: $
		runs-on: ubuntu-latest
		steps:
			- uses: actions/checkout@v4
				with:
					ref: gh-pages
					path: gh-pages

			- uses: actions/download-artifact@v4
				with:
					github-token: $
					run-id: $
					name: publish-badges
					path: gh-pages/badges

			- uses: EndBug/add-and-commit@v9
				with:
					default_author: github_actions
					message: "Update badges"
					add: "badges/*.svg"
					cwd: gh-pages

Key Configuration Values

Project and paths

Coverage inputs

Badge outputs

Release/version outputs

Color thresholds

Badge Template

Default template location:

Supported template placeholders:

Example override:

KIT_TEMPLATE_BADGE_PATH=./my-template.svg badges-ts generate

API Surface (Package Exports)

The package exports include:

See generated TypeDoc for full API details:

Troubleshooting

This site is open source. Improve this page.