chrome-ext-ci-cd

CLI toolkit for Chrome extension CI/CD: validate, version, package, and release.

Zero runtime dependencies. Works with any Chrome extension project using Manifest V3.

Quick Start

npm install -D chrome-ext-ci-cd
npx chrome-ext-ci-cd init
npx chrome-ext-ci-cd release patch

init scaffolds a GitHub Actions workflow, .extensionignore, .nvmrc, and npm scripts into your project. release validates your manifest, bumps the version, packages a .zip, commits, tags, and pushes -- triggering CI.

Commands

validate

Validate manifest.json for Chrome Web Store compatibility.

chrome-ext-ci-cd validate [options]

Options:

| Flag | Description | |------|-------------| | --manifest, -m <path> | Path to manifest.json (default: manifest.json) | | --help, -h | Show help |

Checks: MV3 compliance, version format, icon file existence, permissions audit (flags dangerous permissions), CSP safety (blocks unsafe-eval).

Exit codes: 0 on success, 1 on validation errors. Warnings do not affect the exit code.

npx chrome-ext-ci-cd validate
npx chrome-ext-ci-cd validate --manifest src/manifest.json

package

Package the extension directory into a .zip for distribution.

chrome-ext-ci-cd package [options]

Options:

| Flag | Description | |------|-------------| | --source <dir> | Extension source directory (default: .) | | --output <path> | Output zip file path (default: dist/extension.zip) | | --help, -h | Show help |

Respects .extensionignore patterns plus built-in default exclusions (node_modules, .git, tests, etc.). Reports file count and size. Warns above 50 MB (Chrome Web Store soft limit).

npx chrome-ext-ci-cd package
npx chrome-ext-ci-cd package --source . --output dist/my-ext.zip

bump

Bump the version in manifest.json, create a git commit and annotated tag, and push.

chrome-ext-ci-cd bump <patch|minor|major|x.y.z> [options]

Options:

| Flag | Description | |------|-------------| | --dry-run | Preview version change without making changes | | --manifest, -m <path> | Path to manifest.json (default: manifest.json) | | --help, -h | Show help |

Updates both manifest.json and package.json (if present). Refuses to run if the working tree has uncommitted changes. --dry-run shows what would happen without modifying any files.

npx chrome-ext-ci-cd bump patch
npx chrome-ext-ci-cd bump minor --dry-run
npx chrome-ext-ci-cd bump 2.0.0

release

Run the full release pipeline: validate, bump, and package in sequence.

chrome-ext-ci-cd release <patch|minor|major> [options]

Options:

| Flag | Description | |------|-------------| | --dry-run | Validate (real), bump (preview), skip package | | --manifest, -m <path> | Path to manifest.json (default: manifest.json) | | --source <dir> | Extension source directory (default: .) | | --output <path> | Output zip file path (default: dist/extension.zip) | | --help, -h | Show help |

Stops on first failure with a descriptive error naming which step failed. --dry-run runs validation normally, shows the version bump preview, and skips packaging.

npx chrome-ext-ci-cd release patch
npx chrome-ext-ci-cd release minor --dry-run
npx chrome-ext-ci-cd release major --source src --output dist/ext.zip

init

Scaffold CI/CD files into your Chrome extension project.

chrome-ext-ci-cd init [options]

Options:

| Flag | Description | |------|-------------| | --force, -f | Overwrite existing files | | --help, -h | Show help |

Creates:

• .github/workflows/release.yml -- GitHub Actions workflow for CI/CD
• .extensionignore -- Patterns for files to exclude from the zip
• .nvmrc -- Node version file

Injects npm scripts into package.json:

• ext:validate -- chrome-ext-ci-cd validate
• ext:package -- chrome-ext-ci-cd package
• ext:release:patch -- chrome-ext-ci-cd release patch
• ext:release:minor -- chrome-ext-ci-cd release minor
• ext:release:major -- chrome-ext-ci-cd release major

Warns before overwriting existing files. Use --force to overwrite.

npx chrome-ext-ci-cd init
npx chrome-ext-ci-cd init --force

Manual Setup

If you prefer not to use init, create these files manually:

1. GitHub Actions Workflow

Create .github/workflows/release.yml. The workflow should trigger on version tags (v*) and PRs to main, with jobs for validation, packaging, GitHub Release creation, and optional Chrome Web Store publishing. See the template for a complete example.

2. Extension Ignore

Create .extensionignore in your project root with patterns for files to exclude from the extension zip:

.vscode/
.idea/
docs/
*.md
webpack.config.*
*.psd
*.sketch

Built-in defaults (node_modules, .git, tests, etc.) are always excluded regardless of this file.

3. npm Scripts

Add these scripts to your package.json:

{
  "scripts": {
    "ext:validate": "chrome-ext-ci-cd validate",
    "ext:package": "chrome-ext-ci-cd package",
    "ext:release:patch": "chrome-ext-ci-cd release patch",
    "ext:release:minor": "chrome-ext-ci-cd release minor",
    "ext:release:major": "chrome-ext-ci-cd release major"
  }
}

Requirements

• Node.js 20 or later
• git (for bump and release commands)
• zip (for packaging -- pre-installed on most systems)

License

Proprietary. All rights reserved.