prod-debug

A secure, dev-only CLI tool for debugging production React/SPAs with local source maps using Chrome DevTools Overrides, without deploying source maps publicly.

Overview

prod-debug creates a pre-wired Chromium debugging session that allows you to:

• Debug production builds with local source maps
• Set breakpoints in original source files
• View stack traces with original file names and line numbers
• Keep source maps completely local (never exposed publicly)

Requirements

• Node.js 22.0.0 or higher
• Chrome/Chromium browser
• Local production build directory with .js and .js.map files

Installation

npm install -g prod-debug

Or use with npx:

npx prod-debug <url> --build <path>

Usage

Basic Usage

prod-debug https://app.example.com --build ./build

Options

| Option | Description | |--------|-------------| | <url> | Production URL to debug (required) | | --build <path> | Local production build directory containing .js and .js.map files (required) | | --ssr | Enable SSR mode (partial decoding allowed) | | --browser <path> | Custom Chrome/Chromium binary path | | --keep-profile | Do not delete temp profile on exit (debug only) | | --verbose | Enable debug logs | | --dry-run | Do everything except launching browser |

Examples

Debug a production React app:

prod-debug https://myapp.com --build ./dist

Debug with SSR mode (for apps with large inline scripts):

prod-debug https://myapp.com --build ./dist --ssr

Dry-run to test configuration:

prod-debug https://myapp.com --build ./dist --dry-run --verbose

Use custom Chrome binary:

prod-debug https://myapp.com --build ./dist --browser /path/to/chrome

How It Works

1. Fetch & Parse: Fetches HTML from the production URL and parses all <script> tags
2. Match Artifacts: Matches production JS bundle URLs to local build artifacts by filename and hash
3. Create Profile: Creates a temporary Chrome profile with DevTools Overrides enabled
4. Setup Overrides: Copies local source maps to Chrome's Overrides directory, mirroring production paths
5. Launch Chrome: Launches Chrome with DevTools automatically opened
6. Cleanup: Removes temporary profile on exit (unless --keep-profile is used)

Security & Isolation

• Ephemeral Profile: Uses a brand-new temporary Chrome profile (no extensions, no sync, no cookies)
• Local Source Maps: Source maps never leave your filesystem
• No Network Exposure: Source maps are not served over HTTP
• Automatic Cleanup: All temporary files are deleted on exit

Limitations

• Chromium-only: No Safari support
• Hash Matching: Production JS filenames must match local build artifacts (including hash)
• No Runtime JS: Cannot debug encrypted or runtime-generated JavaScript
• No Retroactive Decoding: Stack traces generated before DevTools opens won't be decoded
• Rebuild Required: If production hash changes, you must rebuild locally

SSR Mode

When using --ssr, the tool allows large inline scripts (which cannot be source-mapped) and provides warnings instead of errors. This is useful for SSR applications where some JavaScript is injected server-side.

Troubleshooting

"No matching build artifact found"

• Ensure your local build directory contains the same JS files as production (with matching hashes)
• Check that source map files (.js.map) exist alongside JS files
• Use --verbose to see detailed matching information

"Hash mismatch"

• Your local build doesn't match production
• Rebuild your application to match production
• Check that you're pointing to the correct build directory

"Large inline script detected"

• Production HTML contains large inline JavaScript that cannot be source-mapped
• Use --ssr flag if this is expected (SSR applications)
• Consider moving inline scripts to external files for better debugging

DevTools Overrides not working

• Ensure Chrome version is 90 or higher
• Check that source maps are being copied to the Overrides directory (use --keep-profile and inspect)
• Verify that the Overrides folder is set correctly in Chrome DevTools Settings

Development

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev <url> --build <path>

License

MIT