Skip to main content

​
Quickstart Guide

Get from zero to your first successful audit in under 5 minutes.

​
Prerequisites

Node.js 16+

Check: node --version

A Node.js Project

Any project with package.json

​
Your First Audit

1

Navigate to Your Project

Open your terminal and cd into any JavaScript or TypeScript project:
cd ~/projects/my-app
Don’t have a project handy? Clone a sample repo:
git clone https://github.com/aryanjha256/stackprobe.git
cd stackprobe
2

Run the Audit

Execute StackProbe with a single command:
npx stackprobe audit
First run may take a few seconds as npx downloads StackProbe. Subsequent runs are instant.
You’ll see output like:
🔍 stackprobe — auditing your project...

✅ license      PASS  (12ms)
  → LICENSE found (MIT)

✅ env          PASS  (8ms)
  → .env and .env.example are in sync

⚠  deps         WARN  (1847ms)
  ⚠ axios is 1 major version(s) behind (you: ^0.27.0, latest: 1.6.8)
  → typescript has a new major version available (you: ^4.9.5, latest: 5.9.3)
  → Only checked 20 of 32 dependencies to avoid rate limiting

✅ engine       PASS  (5ms)
  → engines.node = ">=16.0.0" — looks good

✅ circular     PASS  (234ms)
  → No circular dependencies found across 47 files

────────────────────────────────────────────────
Summary  4 passed  1 warned  in 2106ms

Audit passed with warnings. Consider reviewing them.
3

Understand the Results

StackProbe runs 5 checks and reports:
  • ✅ PASS: Everything looks good
  • ⚠ WARN: Issues to review (won’t fail CI by default)
  • ✗ FAIL: Critical issues that need fixing
  • — SKIP: Check not applicable to this project
Each check shows:
  • Status icon and name
  • Duration in milliseconds
  • Detailed messages with → info, ⚠ warnings, ✗ errors

​
Common First Commands

​
Run All Checks (Default)

stackprobe audit
Runs all 5 checks: deps, env, license, engine, circular

​
Run Specific Checks Only

stackprobe audit --only deps,env
Useful when you only care about certain checks: 
stackprobe audit --only deps

​
JSON Output for CI

stackprobe audit --json
Outputs machine-readable JSON: 
{
  "results": [
    {
      "checkName": "license",
      "status": "pass",
      "messages": [
        {
          "level": "info",
          "text": "LICENSE found (MIT)"
        }
      ],
      "duration": 12
    },
    {
      "checkName": "deps",
      "status": "warn",
      "messages": [
        {
          "level": "warn",
          "text": "axios is 1 major version(s) behind (you: ^0.27.0, latest: 1.6.8)"
        }
      ],
      "duration": 1847
    }
  ],
  "duration": 2106
}
Perfect for parsing in CI scripts.

​
Understanding Check Results

Checks npm packages against the registry.Example output:
⚠  deps         WARN  (1523ms)
  ⚠ lodash is 3 major version(s) behind (you: ^1.0.0, latest: 4.17.21)
  → axios has a new major version available (you: ^0.27.0, latest: 1.6.8)
What to do:
  • Update packages 2+ major versions behind (security risk)
  • Review new major versions for breaking changes
  • Check your package.json and run npm update
StackProbe checks up to 20 packages to avoid npm rate limiting. For full audits, use npm audit or yarn audit.
Compares .env and .env.example for drift.Example output:
⚠  env          WARN  (8ms)
  ⚠ Keys in .env but missing from .env.example: JWT_SECRET, API_KEY
  ⚠ Keys in .env.example but missing from your .env: DATABASE_URL
  → These may be required — check with your team or docs
What to do:
  • Add missing keys to .env.example (without real values)
  • Add missing keys to .env (ask team for values)
  • Keep both files in sync for team onboarding
Checks for a LICENSE file in your project root.Example output:
⚠  license      WARN  (5ms)
  ⚠ No LICENSE file found — open source projects should have one
  → Add a LICENSE file. Not sure which? → https://choosealicense.com
What to do:
  • Visit choosealicense.com to pick a license
  • Add a LICENSE file to your project root
  • Common choices: MIT (permissive), Apache 2.0 (patent protection), GPL (copyleft)
Validates your package.json engines field.Example output:
⚠  engine       WARN  (4ms)
  ⚠ engines.node specifies >= 14, but Node 14 is End-of-Life
  → Consider bumping to >= 18 (current LTS)
What to do:
  • Update engines.node in package.json: 
    {
  "engines": {
    "node": ">=18.0.0"
  }
}
  • Test your app on the new Node version
  • Update your CI/CD to use Node 18+
Detects import cycles in your source code.Example output:
✗  circular     FAIL  (234ms)
  ✗ Found 2 circular dependency chain(s)
  ⚠ src/services/auth.ts → src/models/user.ts → src/services/auth.ts
  ⚠ src/utils/helpers.ts → src/config/index.ts → src/utils/helpers.ts
What to do:
  • Refactor to break the cycle:
    • Extract shared code to a new file
    • Use dependency injection
    • Move types to separate files
  • Circular deps can cause:
    • Runtime errors (undefined imports)
    • Hard-to-debug initialization bugs
    • Module load order issues

​
Exit Codes

StackProbe returns exit codes for CI/CD integration:
​
0
Success
All checks passed or warned (warnings don’t fail by default)
​
1
Failure
One or more checks failed (status: fail)
Example CI usage: 
# Fails the build only if critical issues found
stackprobe audit || exit 1

​
What to Do With Results

1

Fix Critical Issues (FAIL)

Address any checks with ✗ FAIL status immediately:
  • Circular dependencies
  • Incompatible Node versions
  • Missing critical environment variables
These can cause runtime errors or deployment failures.
2

Review Warnings (WARN)

Warnings won’t fail your build but should be addressed:
  • Outdated dependencies (security updates)
  • Missing LICENSE file (legal issues)
  • Env file drift (team onboarding pain)
Schedule time to fix these before they become problems.
3

Add to CI/CD

Once your project passes, add StackProbe to your CI:
.github/workflows/audit.yml
name: StackProbe Audit
on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npx stackprobe audit
See CI Integration for more.
4

Configure for Your Workflow

Customize which checks run and when they fail:
stackprobe.config.js
module.exports = {
  // Skip checks you don't need
  ignore: ['license'],

  // Or run only specific checks
  // only: ['deps', 'env'],

  // Fail on warnings in CI (default: 'error')
  failOn: 'warn'
};
See Configuration for all options.

​
Real-World Example

Here’s a typical first-time audit on a real project: 
🔍 stackprobe — auditing your project...

✅ license      PASS  (10ms)
  → LICENSE found (MIT)

⚠  env          WARN  (7ms)
  ⚠ Keys in .env but missing from .env.example: STRIPE_SECRET_KEY
  → Create .env.example with keys but no real values so others can onboard

⚠  deps         WARN  (2341ms)
  ⚠ react is 2 major version(s) behind (you: ^16.14.0, latest: 18.2.0)
  ⚠ next is 3 major version(s) behind (you: ^10.0.0, latest: 14.1.0)
  → Only checked 20 of 67 dependencies to avoid rate limiting

✅ engine       PASS  (5ms)
  → engines.node = ">=16.0.0" — looks good

✗  circular     FAIL  (445ms)
  ✗ Found 1 circular dependency chain(s)
  ⚠ src/components/Header.tsx → src/lib/auth.ts → src/components/Header.tsx

────────────────────────────────────────────────
Summary  2 passed  2 warned  1 failed  in 2808ms

Audit failed. Fix the issues above before shipping.
Action items from this audit:
  1. Break the circular dependency in Header.tsx ↔ auth.ts
  2. Add STRIPE_SECRET_KEY to .env.example
  3. Schedule React/Next.js upgrade (breaking changes expected)
  4. Re-run audit after fixes: stackprobe audit

​
Next Steps

Configuration

Customize StackProbe for your project

CI Integration

Add to GitHub Actions, GitLab CI, etc.

Check Reference

Deep dive into each check type

CLI Reference

All commands and options
Pro tip: Run stackprobe audit before every release or deployment. Catch issues when they’re easiest to fix.

Build docs developers (and LLMs) love

Get started for freeTalk to us