Pledgepack

A Rust + Zig bundler and dev server. Built with Oxc for transforms, Lightning CSS for styles, Axum for the dev server, and a Zig C ABI for hot-path file I/O and SIMD scanning.

npm package: pledgepack · CLI command: pledge (alias: pledgepack) · Rust crates: pledgepack-*

Architecture

┌─────────────────────────────────────────────────────┐
│                pledgepack CLI                         │
│              (dev / build / serve / bench)            │
├─────────────────────────────────────────────────────┤
│                                                      │
│  ┌─────────────┐    ┌──────────────────────┐        │
│  │   RUST      │    │      ZIG             │        │
│  │ (Orchestrator)│   │  (Hot Paths)         │        │
│  │              │    │                       │        │
│  │ • Engine     │    │ • File I/O           │        │
│  │ • Resolver   │    │ • Module graph       │        │
│  │ • Cache      │    │ • SIMD scanning      │        │
│  │ • Dev server │    │ • Hashing            │        │
│  │ • Optimizer  │    │ • Memory-mapped I/O  │        │
│  │ • JS plugin  │    │                       │        │
│  │   host       │    │                       │        │
│  │ • Oxc transform│  │                       │        │
│  └──────┬───────┘    └──────────┬───────────┘        │
│         │     C ABI (zero-cost)  │                   │
│         └──────────┬─────────────┘                   │
│                    │                                 │
└─────────────────────────────────────────────────────┘

Project Structure

pledgepack/
├── Cargo.toml              # Rust workspace
├── build.zig               # Zig build script
├── build.zig.zon           # Zig config
├── package.json            # npm package (bin: pledgepack, pledge)
├── native-sys/             # Rust FFI bindings to Zig
│   ├── src/lib.rs          # C ABI bindings (Graph, read_file, find_imports)
│   └── zig/                # Zig native library
│       ├── lib.zig         # C ABI exports
│       ├── io.zig          # File I/O (mmap, thread pool)
│       ├── graph.zig       # Arena-allocated module graph
│       ├── simd.zig        # SIMD source scanning
│       └── bench.zig       # Benchmarks
├── crates/
│   ├── cli/                # CLI entry point (binary: pledge)
│   ├── core/               # Engine, config, transform pipeline, HTML, compression, analyzer
│   ├── cache/              # Function-level incremental cache (memory + disk/bincode)
│   ├── resolver/           # Module resolution (node_modules, tsconfig, exports)
│   ├── dev-server/         # Dev server + HMR + CSS HMR + error overlay + proxy
│   ├── optimizer/          # Tree shaking, code splitting, vendor/shared chunks
│   ├── js-plugin-host/     # Vite-compatible JS plugin API (QuickJS via rquickjs)
│   ├── wasm-plugin-host/   # WebAssembly plugin host (WASM module loading)
│   ├── adapter-react/      # React JSX + Fast Refresh adapter (Oxc-based)
│   ├── adapter-solid/      # Solid.js JSX adapter (Oxc-based)
│   ├── adapter-next/       # Next.js adapter (App/Pages Router, SSR, API routes)
│   ├── adapter-tanstack/   # TanStack Router adapter (file-based routing)
│   ├── adapter-pledgestack/ # PledgeStack adapter (React + Rust backend)
│   ├── task-system/        # Parallel task execution engine
│   └── task-system-macros/ # Procedural macros for task-system
└── docs/
    ├── ARCHITECTURE.md     # System architecture deep dive
    ├── CHANGELOG.md        # Development history
    ├── LIMITATIONS.md      # Known limitations
    ├── ROADMAP.md          # Roadmap
    ├── ANALYSIS.md         # Analysis docs
    ├── BENCHMARK.md        # Benchmark docs
    └── CONNECTION.md       # Connection docs

Prerequisites

• Rust (stable, edition 2024)
• Zig (0.16.0+)

Building from Source

git clone https://github.com/pledgeandgrow/pledgepack
cd pledgepack

# Build Zig native library
zig build -Doptimize=ReleaseFast

# Build Rust
cargo build --release

The binary is at target/release/pledge.

Installation

# Global install
npm install -g pledgepack

# Or as a dev dependency
npm install --save-dev pledgepack

Usage

# Development server with HMR
pledgepack dev                    # Start on port 3000
pledgepack dev --port 8080        # Custom port
pledgepack dev --open             # Auto-open browser
pledgepack dev --https            # HTTPS with self-signed certs

# Production build
pledgepack build                  # Build to dist/
pledgepack build --watch          # Watch mode
pledgepack build --profile        # Profile build phases
pledgepack build --type-check     # TypeScript type checking
pledgepack build --check-budgets  # Bundle size budgets

# Serve production build
pledgepack serve                  # Static files on port 4000
pledgepack preview                # Alias for serve

# Project scaffolding
pledgepack create react my-app
pledgepack create vue my-app
pledgepack create svelte my-app
pledgepack create solid my-app
pledgepack create next my-app
pledgepack create tanstack my-app
pledgepack create pledgestack my-app
pledgepack create vanilla my-app
pledgepack create my-app          # Defaults to pledgestack

# Other commands
pledgepack test                   # Run tests (Vitest-compatible API)
pledgepack test --watch            # Watch mode tests
pledgepack test --ui               # Browser UI test mode
pledgepack bench                   # Benchmark build performance
pledgepack analyze                 # Bundle analyzer
pledgepack analyze --graph         # Dependency graph
pledgepack dashboard               # Build telemetry dashboard
pledgepack cache clear             # Clear disk cache
pledgepack cache stats             # Show cache statistics
pledgepack doctor                  # Diagnose build issues
pledgepack init                    # Add PledgePack to existing project
pledgepack migrate                 # Migrate from Vite/webpack/CRA
pledgepack schema                  # Generate JSON Schema for config
pledgepack generate-env-types      # Generate pledge-env.d.ts
pledgepack playground              # Interactive transform REPL
pledgepack completions --shell bash  # Shell completions
pledgepack manpages                # Man pages

Configuration

pledge.config.ts

// pledge.config.ts — config file for PledgePack
// Note: defineConfig is a type-level helper for IDE autocompletion.
// In the npm package, the native binary reads this file directly.

export default {
  // App directory for file-based routing (auto-discovers pages)
  app_dir: 'app',
  // Explicit entry points (optional — use app_dir instead)
  entry: ['src/index.tsx'],
  framework: 'react',
  source_maps: true,
  env_prefix: 'PLEDGE_',
  env_dts: true,
  html_entry: 'index.html',
  compress_gzip: true,
  compress_brotli: true,
  edge_target: 'cloudflare',
  plugins: ['./plugins/my-plugin.ts'],
  image: {
    quality: 80,
    webp: true,
    avif: false,
    max_width: 1920,
    max_height: 1080,
  },
  library: {
    entry: 'src/index.ts',
    formats: ['esm', 'cjs'],
    name: 'MyLib',
    external: ['react'],
    declarations: true,
  },
  https: {
    cert: './cert.pem',
    key: './key.pem',
  },
  server_entry: 'server/index.ts',
  node_polyfills: true,
  define: {
    'process.env.NODE_ID': '"production"',
    '__VERSION__': '"1.0.0"',
  },
  watch: {
    enabled: false,
    debounce_ms: 300,
  },
  dev_server: {
    port: 3000,
    host: 'localhost',
    hmr: true,
    open: false,
    proxy: [
      { path: '/api', target: 'http://localhost:8080', rewrite: true, ws: true }
    ],
  },
  test: {
    include: ['**/*.{test,spec}.{ts,tsx,js,jsx}'],
    exclude: ['node_modules', '.pledge', 'dist'],
    environment: 'node',
    globals: false,
    setup_files: [],
    isolation: 'file',
    coverage: false,
    coverage_reporter: 'text',
    snapshot: true,
    snapshot_dir: '__snapshots__',
    update_snapshots: false,
  },
});

Config resolution order: pledge.config.ts → pledge.config.js → pledge.config.mjs → pledge.json → defaults.

.env Files

Pledge loads environment variables from .env files with the following precedence (highest first):

1. .env.[mode].local
2. .env.[mode]
3. .env.local
4. .env

Variables are injected via import.meta.env.*:

const apiUrl = import.meta.env.PLEDGE_API_URL;
const isDev = import.meta.env.PLEDGE_DEV;

Built-in variables: PLEDGE_DEV, PLEDGE_PROD, PLEDGE_MODE, MODE, DEV, PROD, SSR.

Supported Frameworks

| Framework | Status | File Types | |-----------|--------|------------| | React | Full | .tsx, .jsx, Fast Refresh, automatic JSX runtime | | Solid | Full | .tsx, .jsx, automatic JSX with solid-js | | Vue | Transform | .vue (SFC), scoped CSS, script setup | | Svelte | Transform | .svelte (SFC), scoped CSS, render functions | | Astro | Transform | .astro, frontmatter, islands-ready | | Next.js | Adapter | App Router, Pages Router, API routes, SSR manifest | | TanStack | Adapter | File-based routing, route tree generation | | PledgeStack | Adapter (route discovery + scaffolding) | React frontend + Rust backend, .rs/.psx | | Vanilla TS/JS | Full | .ts, .js, .mjs |

Transform Pipeline

The transform pipeline lives in crates/core/src/transform/ and is split into focused submodules:

• mod.rs — TransformOutput struct + transform() dispatcher (dispatches by ModuleKind)
• js.rs — JS/TS/JSX via Oxc, React Fast Refresh, dynamic import detection
• css.rs — Lightning CSS, CSS Modules, PostCSS/Tailwind, Sass/SCSS
• assets.rs — JSON, static assets, WASM, shaders
• sfc.rs — Vue, Svelte, Astro Single-File Components
• env.rs — Environment variables, define, import.meta.glob
• data.rs — MDX, GraphQL, YAML, CSV, TSV, TOML
• utils.rs — Source maps, Web Worker import transforms

CSS Processing

• Lightning CSS: Production minification, CSS nesting transpilation, autoprefixing
• CSS Modules: *.module.css scoped class names with blake3 content hashing
• PostCSS/Tailwind: @tailwind directives, @apply expansion, base reset, utility classes
• Sass/SCSS: Compilation via grass crate (pure Rust)
• Advanced CSS: composes cross-file resolution, dark mode generation, custom property optimization, scoped CSS for React, nesting polyfill

Asset Handling

• Static assets: import logo from './logo.png' → URL or base64 data URI (with ?inline)
• JSON: Named exports + default export
• WASM: import wasm from './module.wasm' → WebAssembly.instantiateStreaming
• Web Workers: new Worker(new URL('./worker.ts', import.meta.url)) patterns

Code Splitting

• AST-based dynamic import detection via Oxc
• Relative specifiers tracked for chunk splitting
• Dynamic imports marked for separate chunk emission

Dev Server

• On-demand transforms (each request triggers Oxc transform)
• AST-based import rewriting with string fallback
• Alias rewriting (@/components → /src/components)
• Extension fallback (/src/utils.js resolves to utils.ts)
• Import map injection for bare specifiers
• Error overlay with source context and stack traces
• CSS HMR (style tags updated without page reload)
• HTTPS support via rustls
• Dev server proxy (HTTP + WebSocket)
• Source maps in dev responses
• Auto-open browser, network URL display

HMR

• File watcher via notify crate with 200ms debounce
• WebSocket endpoint at /__pledge_hmr
• React Fast Refresh (component state preservation)
• CSS HMR (in-place style tag updates)
• Error reporting via WebSocket
• Server-only hot reload (for SSR/API routes)

Optimizer

• Tree shaking (reachability analysis from entry points)
• Side-effect detection (heuristic-based)
• Vendor splitting (node_modules → separate chunk)
• Shared splitting (modules used by 2+ entries → shared chunk)
• Scope hoisting (ESM imports preserved, modules share scope)

Cache

• Two-tier: in-memory DashMap + disk bincode (persistent)
• Cache key: content hash + function ID + params hash (via blake3)
• Automatic persistence to node_modules/.pledge-cache/
• Cache invalidation by content hash

Resolver

• Relative paths, bare specifiers, recursive node_modules lookup
• tsconfig.json paths support
• Package exports field with conditions (import, require, browser, default)
• Subpath exports, scoped packages, pattern matching
• Extension resolution: .tsx → .ts → .jsx → .js → index.*
• module, main, browser field fallbacks
• Per-(importer, specifier) DashMap caching

JS Plugin Host

• Vite-compatible API: resolveId, load, transform, transformIndexHtml, configureServer, buildStart, buildEnd, generateBundle
• Embedded JS runtime via rquickjs (QuickJS bindings)
• Console support for plugin debugging
• Build integration with lifecycle hooks

Production Output

• Writes transformed modules to dist/ preserving directory structure
• Extensions changed to .js
• Generates index.html with <script type="module"> entry
• Content-hashed filenames for cache busting
• manifest.json mapping source files to output files
• Single-file bundle mode (emit_single_file())
• Gzip + Brotli compression output
• Edge-ready output (Cloudflare Workers, Vercel Edge, Deno Deploy)

Programmatic API

The native binary can be used programmatically via Rust crates:

• pledgepack_core::BuildEngine — Create a build engine instance
• pledgepack_core::transform() — Transform a single module
• pledgepack_resolver::Resolver — Resolve module specifiers
• pledgepack_dev_server::serve() — Start a dev server

Note: The npm package is a binary launcher — it does not export JS functions. For JS-level API, use the CLI commands or write a Rust integration.

Testing

• Vitest-compatible API: describe, it, test, expect with matchers
• Lifecycle hooks: beforeEach, afterEach, beforeAll, afterAll
• Real JS execution via rquickjs (QuickJS) with console.log and require() shim
• TypeScript stripping for QuickJS compatibility
• Watch mode, UI mode, snapshot testing, coverage reporting
• Mock support: vi.fn(), vi.mock(), vi.spyOn(), vi.stubGlobal()

Other Features

• Security: SRI hashes, CSP generation, vulnerability scanning, license compliance
• Node.js Polyfills: 20 built-in modules (buffer, process, path, crypto, stream, etc.)
• Define/Compile-time constants: Replace identifiers with literal values at build time
• Library mode: ESM, CJS, UMD, IIFE output formats with external dependencies
• Bundle analyzer: Interactive HTML report with module sizes and chunk breakdown
• Build profiling: Per-phase timing (parse, transform, optimize, emit)
• Build telemetry dashboard: Web UI with build history and metrics
• JSON Schema generation: For pledge.config.ts IDE autocompletion
• Service worker generation: With caching strategies
• i18n: Translation catalog extraction
• GraphQL code generation: TypeScript types from .graphql schema files

Crate Integrations

• oxc — JS/TS/JSX parsing, transformation, codegen, minification
• lightningcss — CSS minification, nesting, autoprefixing, CSS Modules
• grass — Pure Rust Sass/SCSS compiler
• axum — Dev server with WebSocket support
• tokio — Async runtime
• rayon — Parallel module transforms
• blake3 — Content hashing for cache keys and asset hashing
• rquickjs — Embedded JS runtime (QuickJS bindings) for plugins and tests
• notify — File watcher for HMR and watch mode
• similar — Line-level diff for HMR
• miette — Graphical error diagnostics with source spans
• schemars — JSON Schema generation for config
• dashmap — Concurrent hashmap for cache and resolver
• bincode — Binary serialization for disk cache
• flate2 / brotli — Compression output
• reqwest — Dev server proxy
• rustls / tokio-rustls — HTTPS dev server
• noyalib — YAML config parsing

npm Scripts

{
  "scripts": {
    "dev": "pledgepack dev",
    "build": "pledgepack build",
    "build:profile": "pledgepack build --profile",
    "build:watch": "pledgepack build --watch",
    "preview": "pledgepack preview",
    "serve": "pledgepack serve",
    "cache:clear": "pledgepack cache clear",
    "bench": "pledgepack bench",
    "analyze": "pledgepack analyze",
    "test": "pledgepack test",
    "test:watch": "pledgepack test --watch",
    "gen:env": "pledgepack generate-env-types"
  }
}

License

MIT License (LICENSE).

See docs/ROADMAP.md for the roadmap. See docs/LIMITATIONS.md for known limitations. See docs/ARCHITECTURE.md for the full architecture deep dive.