🚢 Shipcheck

Know before you ship.

One command that tells a JavaScript/TypeScript developer whether their project is actually ready to deploy.

npx @rumlover/shipcheck

Quick Start • Terminal Preview • The 6 Pillars • CI/CD Setup • Configuration • Security & Privacy

⚡ The Problem

Before hitting Deploy, every developer mentally runs a high-stakes checklist:

• ❌ Did I leave http://localhost:3000 hardcoded in any API client or service?
• ❌ Is my .env file accidentally unignored or actively tracked in Git?
• ❌ Did someone accidentally prefix a Stripe Secret Key with NEXT_PUBLIC_ or VITE_?
• ❌ Are stray console.log statements dumping auth tokens to browser dev tools?
• ❌ Is the deployment branch dirty, detached, or missing a lockfile?

Shipcheck automates this entire pre-flight verification in under 700ms. No fluff, no fake gamified scores—just concrete, high-signal checks that save you from 2 AM production fires.

🚀 Quick Start

Run it directly in any JavaScript or TypeScript project without installing:

npx @rumlover/shipcheck

Or install globally:

npm install -g @rumlover/shipcheck
shipcheck

Run in strict mode (fails on warnings too):

npx @rumlover/shipcheck --strict

🖥️ Terminal Preview

SHIPCHECK v1.0.0
Scanning ./my-saas-app...
────────────────────────────────────────

Environment
  ✓ .env files ignored by Git
  ✓ Environment template in sync (.env.example)
  ✗ Potential secret exposed to client: NEXT_PUBLIC_STRIPE_SECRET_KEY
    Location: src/config/stripe.ts:12
    Why this matters:
    Variables with frontend prefixes (like NEXT_PUBLIC_ or VITE_) are embedded
    directly into client browser bundles, exposing private credentials to all users.

    Suggested fix:
    Remove the public prefix and keep "NEXT_PUBLIC_STRIPE_SECRET_KEY" strictly on the server side.

Security
  ✓ No hardcoded secrets detected
  ✓ No private cryptographic keys detected
  ✓ CORS configurations do not use insecure wildcard or credential combinations
  ✓ TLS verification is active and debug settings are not exposed

Dependencies
  ✓ Found dependency lockfile: package-lock.json
  ✓ Lockfile configuration consistent
  ✓ No known critical/high vulnerabilities detected

Codebase
  ✓ tsconfig.json configured with strict type checking
  ✓ package.json defines a typecheck script for CI verification
  ✓ package.json defines a "build" script
  ⚠ 3 console.log/debug statement(s) detected
    Location: src/controllers/user.ts:48 (and 2 more)

Production
  ✗ 1 localhost URL(s) found in production code
    Location: src/services/api.ts:24 (http://localhost:8080/v1)
    Why this matters:
    Localhost URLs will fail when visited by end users because the client or cloud
    container attempts to connect to its own local loopback interface.

    Suggested fix:
    Replace hardcoded localhost URLs with environment variables (e.g. process.env.API_BASE_URL).

Git
  ✓ Directory is a valid Git repository
  ✓ Working tree clean
  ✓ Active branch is standard release branch (main)
  ✓ No secret .env files or cryptographic private keys tracked in Git index

────────────────────────────────────────

23 checks

  ✓ 19 passed
  ⚠ 2 warnings
  ✗ 2 errors (blockers)

NOT READY TO SHIP

🛡️ The 6 Pillars of Checks

Shipcheck inspects the six most critical vectors where deployment mistakes happen:

1. 🌐 Environment

• Gitignored .env Files: Guarantees .env, .env.local, .env.production, and staging files are excluded in .gitignore.
• .env.example Template Sync: Verifies all variables declared in .env.example are present in your local environment.
• Client-Exposed Secrets: Detects frontend framework variables (NEXT_PUBLIC_*, VITE_*, PUBLIC_*, EXPO_PUBLIC_*, REACT_APP_*) holding sensitive keys (SECRET, PRIVATE, PASSWORD, API_KEY) or live credentials.
• Undeclared Referenced Variables: Catches process.env.VAR or import.meta.env.VAR calls in source code that are missing from all .env files.
• Unused Variables: Identifies stale environment variables cluttering your .env.

2. 🔐 Security

• Hardcoded Secrets & Tokens: Conservative heuristic scanning for live tokens (AWS AKIA..., OpenAI sk-..., GitHub ghp_..., Stripe sk_live_..., Slack, Google API keys, Bearer tokens).
• Private Cryptographic Keys: Detects embedded RSA, EC, DSA, OpenSSH, or PGP private keys.
• Permissive CORS Settings: Flags dangerous patterns like origin: "*" combined with credentials: true.
• Insecure TLS & Debug Leaks: Flags disabled SSL verification (rejectUnauthorized: false, NODE_TLS_REJECT_UNAUTHORIZED='0') and raw stack traces leaked into client responses.

3. 📦 Dependencies

• Deterministic Lockfiles: Verifies presence of package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lock.
• Lockfile Consistency: Warns against competing lockfiles (e.g. npm + Yarn) or mismatches with the packageManager field in package.json.
• Safe Vulnerability Audit: Checks for known critical and high-severity CVEs with offline-safe fallback.

4. 💻 Codebase

• TypeScript Configuration: Validates tsconfig.json, strict type checking, and presence of a typecheck script.
• Build & Test Scripts: Ensures standard build and automated test runner scripts are declared in package.json.
• Production Console Logs: Scans production source files for stray console.log / console.debug statements.
• Unresolved TODOs: Highlights leftover TODO, FIXME, and HACK comments in production code.

5. 🚀 Production

• Hardcoded Localhost URLs: Prevents shipping http://localhost, 127.0.0.1, or local port bindings to production.
• Development Flag Overrides: Detects hardcoded NODE_ENV = 'development', BYPASS_AUTH = true, or mock triggers in production code.

6. 🐙 Git

• Repository Detection: Confirms repository initialization.
• Clean Working Tree: Flags uncommitted changes or untracked modifications.
• Release Branch Check: Detects detached HEAD states or unvetted feature branches.
• Tracked Sensitive Files: Uses git ls-files to ensure no .env or certificate keys were accidentally committed into Git index history.

🚦 Severity Model & Exit Codes

| Status | Symbol | Meaning | | ----------- | :----: | --------------------------------------------------------------------- | | PASS | ✓ | Checked and verified with no issues found. | | WARNING | ⚠ | Non-blocking recommendation or item requiring developer review. | | ERROR | ✗ | High-risk issue likely to break or compromise a production release. | | SKIPPED | ○ | Check was skipped due to explicit configuration or environment rules. |

Exit Codes for CI/CD

• 0: Ready to ship! No blocking errors (or warnings only in normal mode).
• 1: Not ready to ship. One or more blocking errors (or warnings when --strict is enabled).
• 2: Internal execution or configuration error.

⚙️ CLI Options

| Flag | Description | Default | | ------------------- | --------------------------------------------------------------------- | :---------: | | [path] | Target directory to scan | "." | | -h, --help | Show usage documentation | — | | -v, --version | Output version number | — | | --strict | Fail (exit code 1) on warnings as well as errors | false | | --json | Output machine-readable JSON format | false | | --ci | Concise output mode for CI runners | false | | --verbose | Show all checks including skipped and diagnostics | false | | --category <name> | Filter by category (env, security, deps, code, prod, git) | All | | --config <path> | Specify custom configuration file | Auto-detect |

🛠️ Configuration

Shipcheck requires zero configuration by default.

To customize rules, create a shipcheck.config.json (or .shipcheckrc.json, or "shipcheck" in package.json):

{
  "ignore": ["codebase.console-log", "codebase.todo"],
  "checks": {
    "security": true,
    "environment": true,
    "dependencies": true,
    "codebase": true,
    "production": true,
    "git": true
  },
  "exclude": ["fixtures/**", "generated/**", "legacy/**"],
  "strict": false
}

🔄 CI/CD Integration

GitHub Actions

Add Shipcheck to .github/workflows/deploy.yml before your build or deployment step:

name: Production Pre-Flight Check

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  shipcheck:
    name: Verify Ship Readiness
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install Dependencies
        run: npm ci

      - name: Run Shipcheck
        run: npx @rumlover/shipcheck --ci --strict

Git Pre-Push Hook (Husky)

Prevent teammates from pushing broken code:

# .husky/pre-push
npx @rumlover/shipcheck --strict

📊 JSON Output Schema

Shipcheck provides machine-readable JSON output for building PR comments, Slack bots, or release pipelines:

npx @rumlover/shipcheck --json > shipcheck-report.json

{
  "version": "1.0.0",
  "project": "/Users/developer/my-app",
  "timestamp": "2026-09-27T14:26:28.081Z",
  "summary": {
    "total": 23,
    "passed": 21,
    "warnings": 2,
    "errors": 0,
    "skipped": 0,
    "readyToShip": true,
    "durationMs": 680
  },
  "results": [
    {
      "id": "production.localhost-url",
      "category": "production",
      "title": "No hardcoded localhost URLs in production code",
      "status": "pass",
      "message": "Production code does not contain hardcoded localhost URLs"
    }
  ]
}

🔒 Security & Privacy

• 100% Local Execution: Shipcheck runs entirely on your local machine or CI runner. No source code or file contents are ever uploaded to any server.
• Zero Telemetry: No analytics, tracking pixels, or phone-home requests.
• Secret Redaction: Any matched token or password is automatically masked (sk_l...def [REDACTED]). Shipcheck never prints raw secrets to terminal logs or JSON reports.
• Non-Destructive: Shipcheck only reads files statically and never executes arbitrary build or test scripts without permission.

👤 Author

Created and maintained with ❤️ by Abhinav Amrute.

Contributions, feature suggestions, and bug reports are welcome! Check out our Contributing Guide.

📄 License

This project is open-source and licensed under the MIT License.