miniread

Transform minified JavaScript/TypeScript into a more readable form using deterministic AST-based transforms.

Core concept: stabilized names

A stabilized name is an identifier that should stay stable between different minified versions. In miniread, stabilized identifiers start with $. Transforms treat these as already processed and skip renaming them. Adding stabilized names is the main function of transforms.

There are two main kinds:

• Semantic stable names (readable + deterministic in-scope), for example $timeoutId or $caughtError
• Hash-based stable names: top-level $h_<hash>, nested/factory-local $f_<hash>, and deferred top-level $v_<hash>

Why stabilized names exist:

• Remove minifier rename noise so diffs track logic changes instead of arbitrary identifier churn
• Coordinate transforms: $-prefixed bindings are treated as already stabilized and skipped by later rename passes
• Keep output deterministic across runs and versions (the same input should produce the same output)

This is the core mechanism behind reproducible output and more useful diffs between minified bundle versions.

Install

npm install --global miniread

Quick start

miniread --input ./minified --output ./readable
cat bundle.min.js | miniread > bundle.js
miniread --list-transforms
miniread --input ./minified --output ./readable --transforms recommended
miniread --input ./minified --output ./readable --dry-run
miniread --input ./minified --output ./readable --workers 8
miniread --input ./minified --output ./readable --ignore-dirs dist,coverage
miniread --input ./minified --output ./readable --safe-stabilize-top-level-bindings

When scanning input directories, miniread ignores common heavy folders by default: .git, node_modules, coverage, .next, .nuxt, dist, build, out, and .cache.

Use --ignore-dirs <comma-separated-names> to add more directory names to the ignore set (matching is case-insensitive).

Output stability

The recommended preset includes stabilize-top-level-bindings, which renames program-scope bindings to stable hash-based names ($h_<hash>).

By default, this transform runs even when it detects code patterns (like eval) that could make the output non-runnable. Use --safe-stabilize-top-level-bindings or set MINIREAD_UNSAFE_STABILIZE_TOP_LEVEL_BINDINGS to a falsy value (0, false, no, or empty string) to skip renaming in such cases.

Examples

Find the most common identifiers in a minified bundle

cat bundle.min.js | miniread | grep -oE '[A-Za-z_][A-Za-z0-9_]+' | sort | uniq -c | sort -rn | head -20

Locate error-throwing code paths quickly

cat bundle.min.js | miniread | grep -n "throw new" | head -20

Use transform metadata in scripts (TSV)

miniread --list-transforms --format tsv | tail -n +2 | cut -f1

Agent Rule

Add to your CLAUDE.md or AGENTS.md:

# Rule: `miniread` Usage

Run `npx -y miniread --help` to learn available options.

Use `miniread` when you need readable JavaScript/TypeScript from minified input for review, diffing, or grepping; it works as a stdin/stdout filter so it composes well with Unix pipelines.

Development Workflows

Development workflow/tooling documentation lives under development-workflows/:

• development-workflows/AGENTS.md — shared development tooling and workflow helper docs
• development-workflows/new-transform.md — transform iteration workflow
• development-workflows/improve-transform-performance.md — runtime performance optimization workflow
• development-workflows/improve-transform-coverage.md — coverage improvement workflow

License

MIT