@getforma/compiler

@getforma/compiler

Compiler and build plugins for FormaJS. Transforms h() calls into pre-compiled templates for faster rendering, handles "use server" function transforms, and emits FMIR binary for Rust SSR.

This is an optimization layer — FormaJS works without it. Add the compiler when you want faster initial renders or Rust-based SSR.

Install

npm install -D @getforma/compiler

Vite Plugin — formaCompiler

Transforms h() calls into template() + cloneNode() at build time. Instead of creating DOM elements one by one at runtime, the browser clones a pre-built template — significantly faster for complex component trees.

// vite.config.ts
import { defineConfig } from "vite";
import { formaCompiler } from "@getforma/compiler";

export default defineConfig({
  plugins: [formaCompiler()],
});

Before (runtime):

h("div", { class: "card" },
  h("h2", null, "Title"),
  h("p", null, () => description()),
)

After (compiled):

const _tmpl = template("<div class='card'><h2>Title</h2><p></p></div>");
const _root = _tmpl.cloneNode(true);
createEffect(() => { _root.querySelector("p").textContent = description(); });

Options

formaCompiler({
  // Include/exclude file patterns (default: all .ts/.tsx/.js/.jsx)
  include: ["src/**/*.tsx"],
  exclude: ["node_modules"],
})

Server Functions — formaServer

Transforms functions with the "use server" directive into RPC stubs (client build) or registered endpoints (server build).

// vite.config.ts
import { defineConfig } from "vite";
import { formaCompiler, formaServer } from "@getforma/compiler";

export default defineConfig({
  plugins: [
    formaCompiler(),
    formaServer({ mode: "client" }), // or "server"
  ],
});

Source:

async function createTodo(text: string) {
  "use server";
  return db.insert("todos", { text });
}

Client output:

import { $$serverFunction } from "@getforma/core/server";
const createTodo = $$serverFunction("/rpc/createTodo_a1b2c3");

Server output:

import { registerServerFunction } from "@getforma/core/server";
async function createTodo(text: string) {
  return db.insert("todos", { text });
}
registerServerFunction("/rpc/createTodo_a1b2c3", createTodo);

esbuild SSR Plugin — formaSsrPlugin

Emits FMIR (Forma Module IR) binary files for Rust-based server-side rendering. Only needed with the full Forma stack (forma-ir + forma-server).

import { formaSsrPlugin } from "@getforma/compiler";

// Used by @getforma/build, not typically called directly

Component Analyzer

Parses entry points to extract component trees, signal defaults, and island boundaries for IR emission.

import { ComponentAnalyzer } from "@getforma/compiler";

const analyzer = new ComponentAnalyzer();
const entry = analyzer.parseEntryPoint("src/app.tsx");
const component = analyzer.parseComponentFile(entry.importPath, entry.componentName);

When Do You Need This?

Scenario	Need compiler?
Learning FormaJS, building prototypes	No
Production app with Vite	Optional — adds faster rendering
"use server" functions (RPC)	Yes — transforms the directive
Rust SSR with forma-server	Yes — emits FMIR binary
HTML Runtime (data-* directives)	No — runtime handles everything

Peer Dependencies

• vite >=5.0.0 (optional — for Vite plugins)
• esbuild >=0.17.0 (optional — for esbuild SSR plugin)

Part of the Forma Stack

Frontend (TypeScript)

Package	Description
@getforma/core	Reactive DOM library — signals, h(), islands, SSR hydration
@getforma/compiler	This package — h() optimization, server transforms, IR emission
@getforma/build	Production pipeline — 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