Scripts Reference

ReeWeb's package.json defines a set of scripts for static site generation, development, and maintenance. This page lists every script with its exact command and purpose.

Development Scripts

How bun dev Works

bun dev runs scripts/dev/orchestrate.ts, which performs the one-shot setup steps (bun dynamic:sync, image preparation, and an initial CSS build - dynamic:sync is a no-op unless REEPOLEE_API_URL is set, see below), then spawns two long-running processes side by side:

1. tailwindcss --watch=always - the Tailwind CSS watcher, recompiling on every file change (--watch=always is required: without it the watcher exits as soon as its stdin closes)
2. bun --hot --no-clear-screen scripts/dev.ts - the dev server (scripts/dev.ts), serving templates with live reload

The orchestrator also watches .env and config/ and restarts the whole dev child process when either changes (Bun's --hot can't pick up those at runtime). Open http://localhost:3000 once they are running.

Dynamic Asset Sync (dynamic:sync)

When a ReeWeb site is paired with a Reepolee app as its data source, dynamic:sync fetches the assets (images and documents) referenced by Reepolee-managed data and writes them into the project so they ship as static files. It reads the Reepolee origin from REEPOLEE_API_URL and skips silently when that variable is unset, so a standalone ReeWeb site is unaffected. It runs first in both bun dev and bun ssg, and is incremental (pass --force to re-sync everything). See ReeWeb & Reepolee for the data-source model.

The dev server is documented in detail on the Dev Server page.

SSG Scripts

Responsive Images (prepare:images)

scripts/prepare_images.ts turns full-size originals in assets/images/ into width-stepped WebP + JPEG variants in src/public/images/responsive/ (git-ignored), using Bun's native Bun.Image - no external dependency. It runs before bun ssg and as one of bun dev's one-shot setup steps, and is incremental (mtime-based): warm runs are near-instant, and editing one original rebuilds only that image. Widths and quality live in config/responsive_images.ts. See the Responsive Images recipe for detail.

SSG Options

All SSG scripts accept these options via command-line flags:

bun scripts/ssg.ts [options]

Pass --verbose directly for verbose output:

bun scripts/ssg.ts --public ./src/public --dist ./dist --verbose

The SSG pipeline is documented on the SSG Pipeline page.

CSS Scripts

Note: bun ssg includes the CSS build, image preparation, sitemap generation, and RSS generation for a complete production-ready generation pass.

The Tailwind setup is documented on the Tailwind CSS Setup page.

SEO Scripts

Both should be run after bun ssg - they read from the generated dist/ directory. Neither command hardcodes a site URL; they read the absolute origin from the SITE_URL environment variable (see Configuration), so set SITE_URL in .env or the SSG environment before running them.

Sitemap Options

bun scripts/generate_sitemap.ts [options]

See the Sitemap Generator page for per-page frontmatter options.

RSS Options

bun scripts/generate_rss.ts [options]

See the RSS Generator page for per-post frontmatter options.

Installation

The install task initialises Git, creates .env from .env.example when needed, runs bun install, and fetches ReeWeb's formatter and vendor assets. bun dev and bun ssg prepare images and build CSS when they run.

Publishing

bun publisher is the operations dashboard that re-renders and deploys the site when content changes - manually, on a git commit, or on a signal from a paired Reepolee app. Run bun publisher --render to force a render against an already-running instance. The Deploy button (and any deploy flow) runs bun cf:deploy under the hood. The full workflow and its PUBLISHER_* configuration are documented on the Publisher page.

Formatting

package.json Reference

The scripts above are defined in package.json under the "scripts" key. You can add your own scripts at any time - there's no ReeWeb-specific structure to follow:

{
    "scripts": {
        "dev": "bun scripts/dev/orchestrate.ts",
        "development": "bun --hot --no-clear-screen scripts/dev.ts",
        "dynamic:sync": "bun scripts/sync_dynamic_assets.ts",
        "prepare:images": "bun scripts/prepare_images.ts",
        "css:build": "tailwindcss -i ./src/css/style.css -o ./src/public/css/style.min.css --minify",
        "css:watch": "tailwindcss -i ./src/css/style.css -o ./src/public/css/style.min.css --minify --watch=always",
        "ssg": "bun run dynamic:sync && bun run prepare:images && bun css:build && bun scripts/ssg.ts --public ./src/public --dist ./dist && bun run og:images && bun run sitemap && bun run rss && bun run ssg:search",
        "og:images": "bun scripts/generate_og_images.ts --dist ./dist",
        "rss": "bun scripts/generate_rss.ts --public ./src/public --dist ./dist",
        "sitemap": "bun scripts/generate_sitemap.ts --public ./src/public --dist ./dist",
        "ssg:search": "bun scripts/generate_search_index.ts --public ./src/public --dist ./dist",
        "format": "reettier",
        "preview": "bun scripts/preview.ts",
        "mcp": "bun scripts/mcp/index.ts",
        "publisher": "bun scripts/publisher.ts",
        "engine:check": "bun scripts/engine_drift_check.ts",
        "get:pre": "bun get:zod && bun get:hljs && bun get:reettier && bun get:reesql && bun get:vips",
        "reeweb:install": "bun get:pre && bun scripts/install.ts"
    }
}