01/quickstart

Installation & Quick Start

Initialize unpeek in any JavaScript or TypeScript project in under 30 seconds with zero manual AST configuration.

One-Command Initialization (npx unpeek init)

Run npx unpeek init at the root of your repository. The CLI inspects your package.json and build configuration to detect Next.js, Vite, Webpack, or Vanilla JS setups.

It automatically wires a postbuild hook (`unpeek protect`) into your package.json scripts and appends `.unpeek-maps/` to `.gitignore` so extracted source maps are never committed or deployed to public CDNs.

Terminal: Interactive / Zero-Config Init
# 1. Initialize in your project root
npx unpeek init

#   ▛▀▀▜  unpeek 1.12.0
#   ▙▄▄▟  client bundle protection
#
#   PROJECT ──────────────────────────────────────
#   framework            next
#   postbuild            unpeek protect (added)
#   vault                .unpeek-maps/ (added)
#
#   postbuild wired. maps stay private from the first build.
#   run your build to protect the first bundle.

Running Standalone Protection (npx unpeek protect)

Whenever you run `npm run build` / `pnpm build`, the `postbuild` script automatically invokes `unpeek protect`. You can also invoke it directly in CI/CD pipelines with a deterministic polymorphic seed.

Terminal: Postbuild Protection & Summary
# Run manually or via npm/pnpm postbuild
npx unpeek protect --seed 482910

#   ▛▀▀▜  unpeek 1.12.0
#   ▙▄▄▟  client bundle protection
#
#   PROJECT ──────────────────────────────────────
#   framework            next
#   tier                 Tier 1 (default: <2% CPU, <15% Gzip)
#   output               .next/static/chunks
#   bundles              18
#
#   CALL GRAPH ───────────────────────────────────
#   hot path exempt      24  0% tax
#   cold path protected  61
#
#   TRANSFORM ────────────────────────────────────
#   string vault         312 literals  O(1) memo
#   symbol mangling      489 bindings
#
#   OUTPUT ───────────────────────────────────────
#   source maps          18 moved -> .unpeek-maps/
#   gzip                 284.12 KB -> 302.36 KB  +6.42%
#   elapsed              142 ms
#
#   done. maps are private. hot path untouched.

Project Configuration: unpeek.config.ts (defineConfig)

unpeek operates zero-config by default through automatic framework discovery. For custom hot-path heuristics, fine-grained string vault thresholds, mangler reservations, or private map paths, place an `unpeek.config.ts` (or `.js`, `.mjs`, `.cjs`, `.json`) at the project root.

Use `defineConfig` imported from `unpeek` for full TypeScript autocomplete, inline schema documentation, and strict type verification:

unpeek.config.ts: Configuration File & Options
import { defineConfig } from "unpeek";

export default defineConfig({
  // Hot-path heuristics & caller propagation exemptions
  hotPath: {
    customAnimationCalls: ["requestAnimationFrame", "useFrame"],
    customHooks: ["useSpring", "useGesture"],
    maxPipelineCallers: 2,
  },
  // O(1) string vault & syntax noise filters
  vault: {
    minStringLength: 4,
    cssFramework: "tailwind",
    polymorphicDecoys: true,
  },
  // Lexical binding & symbol mangler rules
  mangler: {
    reservedIdentifiers: ["__NEXT_DATA__", "process"],
  },
  // Private source map extraction vault
  sourcemaps: {
    keepPrivate: true,
    vaultDir: ".unpeek-maps",
  },
});