@getforma/build

Production build pipeline for FormaJS applications. Handles esbuild bundling, CSS generation, content hashing, Brotli/gzip compression, asset manifest generation, SSR IR emission, and WASM compilation — all from a single config.

This replaces writing your own build script. If you're using Vite for development and need a production pipeline with content hashing and SSR, this is the tool.

Install

npm install -D @getforma/build

This installs esbuild automatically. For SSR features (FMIR emission), also install the compiler:

npm install -D @getforma/compiler

Quick Start

// build.ts
import { build } from "@getforma/build";

await build({
  entryPoints: [
    { entry: "src/app.tsx", outfile: "app.js" },
  ],
  routes: {
    "/": { js: ["app"], css: ["app"] },
  },
  outputDir: "dist",
});

npx tsx build.ts

This bundles your app with esbuild, applies the FormaJS compiler transforms, content-hashes all assets, generates Brotli + gzip compressed versions, and writes an asset manifest.

What It Does

| Step | What happens | |------|-------------| | Bundle | esbuild bundles each entry point with JSX transform (jsxFactory: "h") | | Compile | @getforma/compiler transforms h() calls to template() + cloneNode() | | CSS | Runs Tailwind CLI or concatenates CSS files | | Hash | SHA-256 content hash appended to filenames (app.a1b2c3d4.js) | | Compress | Brotli (level 11) + gzip (level 9) for .js and .css | | Manifest | Writes manifest.json mapping source filenames → hashed filenames | | SSR | (Optional) Emits FMIR binary for Rust server-side rendering | | WASM | (Optional) Runs wasm-pack build for the Rust IR walker | | Budget | Warns if route brotli size exceeds threshold (default 200KB) |

Configuration

import { build, type BuildConfig } from "@getforma/build";

const config: BuildConfig = {
  // Required
  entryPoints: [
    { entry: "src/home/app.tsx", outfile: "home.js" },
    { entry: "src/dashboard/app.tsx", outfile: "dashboard.js" },
  ],
  routes: {
    "/": { js: ["home"], css: ["home"] },
    "/dashboard": { js: ["dashboard"], css: ["dashboard"] },
  },
  outputDir: "dist",

  // Optional
  cssEntries: [
    { type: "tailwind", input: "src/app.css", output: "app.css" },
  ],
  fontDir: "src/fonts",              // Copy .woff2 files to dist
  ssr: true,                          // Enable FMIR emission
  ssrEntryPoints: {
    home: "src/home/HomeIsland.tsx",
    dashboard: "src/dashboard/DashboardIsland.tsx",
  },
  wasm: { crateDir: "../crates/forma-ir" },  // Build WASM walker
  budgetThreshold: 200_000,           // Warn at 200KB brotli per route
  formaAlias: "./node_modules/@getforma/core/dist/index.js",
  serverInlined: ["sw.js"],           // Files to keep unhashed copies of
};

await build(config);

Output Structure

dist/
├── home.a1b2c3d4.js         # Content-hashed bundle
├── home.a1b2c3d4.js.br      # Brotli compressed
├── home.a1b2c3d4.js.gz      # Gzip compressed
├── home.e5f6g7h8.css
├── home.e5f6g7h8.css.br
├── dashboard.i9j0k1l2.js
├── home.m3n4o5p6.ir          # FMIR binary (if ssr: true)
├── forma_ir.q7r8s9t0.js      # WASM loader (if wasm configured)
├── forma_ir_bg.u1v2w3x4.wasm # WASM binary
├── inter.woff2                # Copied fonts
├── sw.js                      # Service worker (unhashed copy)
├── manifest.json              # Asset manifest
└── manifest.json.br

Asset Manifest

The manifest maps source filenames to content-hashed filenames:

{
  "version": 1,
  "build_hash": "sha256-of-all-asset-names",
  "assets": {
    "home.js": "home.a1b2c3d4.js",
    "home.css": "home.e5f6g7h8.css",
    "home.ir": "home.m3n4o5p6.ir"
  },
  "routes": {
    "/": {
      "js": ["home.a1b2c3d4.js"],
      "css": ["home.e5f6g7h8.css"],
      "ir": "home.m3n4o5p6.ir",
      "total_size_br": 45230
    }
  }
}

The Rust server (forma-server) reads this manifest to serve assets with correct cache headers and resolve hashed filenames.

When Do You Need This?

| Scenario | Need @getforma/build? | |----------|----------------------| | Learning / prototyping | No — use Vite | | Production with Vite only | No — Vite handles it | | Production with content hashing + compression | Yes | | Rust SSR with forma-server | Yes — emits FMIR + manifest | | Multiple route entry points | Yes — handles multi-page builds |

Compiler vs Build

| | @getforma/compiler | @getforma/build | |---|---|---| | What it is | Vite/esbuild plugins | Full build pipeline | | Use case | Add to existing Vite config | Replace your build script | | Includes compiler? | — | Optional peer dependency (needed for SSR only) | | Content hashing | No | Yes | | Compression | No | Yes (Brotli + gzip) | | Manifest | No | Yes | | SSR IR emission | Plugin only | Integrated | | Install separately? | Yes | Yes (pulls in compiler) |

Part of the Forma Stack

Frontend (TypeScript)

| Package | Description | |---|---| | @getforma/core | Reactive DOM library — signals, h(), islands, SSR hydration | | @getforma/compiler | Vite plugin — h() optimization, server transforms, IR emission | | @getforma/build | This package — bundling, hashing, compression, manifest |

Backend (Rust)

| Package | Description | |---|---| | forma-ir | FMIR binary format — parser, walker, WASM exports | | forma-server | Axum middleware — SSR page rendering, asset serving, CSP headers |

Full Framework

| Package | Description | |---|---| | @getforma/create-app | npx @getforma/create-app — scaffolds a Rust server + TypeScript frontend project |

License

MIT