Assets CLI

The pidgn assets command manages your project’s JavaScript and CSS assets. It scaffolds a starter asset directory, bundles and fingerprints files with Bun, and provides a watch mode for development.

Commands

Command	Description
pidgn assets setup	Generate starter asset files, package.json, and bunfig.toml.
pidgn assets setup --ssr	Same as setup, plus SSR worker script and sample React component.
pidgn assets build	Bundle, minify, fingerprint, and generate the asset manifest.
pidgn assets watch	Watch source files and rebuild on change (Bun watch mode).

setup

pidgn assets setup

Creates the following structure:

assets/
  app.js          # Starter JavaScript entry point
  app.css         # Starter CSS file
public/
  assets/         # Output directory (created if missing)
package.json      # Bun/npm dependencies
bunfig.toml       # Bun build configuration

After setup, install dependencies:

bun install

SSR setup

pidgn assets setup --ssr

Creates the standard files above, plus:

assets/
  ssr-worker.js           # Bun worker script for server-side rendering
  components/
    App.jsx               # Sample React component

The package.json includes react and react-dom as dependencies when using --ssr.

build

pidgn assets build

The build command performs these steps:

1. Bundle JavaScript — runs bun build assets/app.js --outdir public/assets --minify to produce a minified bundle.

2. Copy CSS — copies assets/app.css to public/assets/app.css.

3. Fingerprint files — computes an FNV-1a hash of each output file and creates a fingerprinted copy (e.g. app-2b3e914a.js).

4. Generate manifest — writes public/assets/assets-manifest.json mapping original filenames to fingerprinted filenames.

Manifest format

{
  "app.js": "app-2b3e914a.js",
  "app.css": "app-7f1dc3e8.css"
}

The asset middleware reads this manifest at runtime to resolve assetPath("app.js") to the fingerprinted URL.

watch

pidgn assets watch

Starts Bun in watch mode. When any file under assets/ changes, the build runs again automatically. Use this alongside pidgn server during development:

# Terminal 1: application server with auto-restart
pidgn server

# Terminal 2: asset rebuilds on change
pidgn assets watch

Typical workflow

1. One-time setup

   pidgn assets setup
   bun install

2. During development — run both commands in separate terminals:

   pidgn server          # Rebuilds Zig on change
   pidgn assets watch    # Rebuilds assets on change

3. For production — build once before deploying:

   pidgn assets build
   zig build -Doptimize=.ReleaseSafe

Next steps

• Asset Pipeline — how the middleware loads the manifest and resolves paths
• Live Reload — automatic browser refresh on file changes
• Server-Side Rendering — use setup --ssr to add React SSR
• Dev Server — automatic application rebuilds during development
• CLI Overview — full list of pidgn CLI commands