@sigil-dev/compiler

Compile-time JSX transform for Sigil.
Turns reactive macros and JSX into direct DOM operations with a tiny runtime overhead.

bun add -d @sigil-dev/compiler

What it does

The compiler runs at build time and does two things:

1. Transforms reactive macros into signal primitives
This helps you avoid footguns ~~which should hardly be possible, we're not react~~

// you write:
let count = $state(0);
let doubled = $derived(count * 2);

$effect(() => {
  console.log(doubled);
});

// compiler outputs:
const count = createSignal(0);
const doubled = createMemo(() => count() * 2);

createEffect(() => {
  console.log(doubled());
});

2. Transforms JSX into imperative DOM

// you write:
const el = <div class="box">{count}</div>;

// compiler outputs (dom mode):
const el = document.createElement("div");
el.className = "box";
const t = document.createTextNode("");
createEffect(() => { t.data = String(count()); });
el.appendChild(t);

There's no virtual DOM involved, and none of the nonsense involved with it. Output is either a string or DOM manipulation. You won't fight with the runtime over what actually changed and what didn't

Modes

Three output modes for the full SSR lifecycle:

| Mode | Use | Output | |------|-----|--------| | dom | Client SPA navigation | Imperative DOM calls | | ssr | Server render | HTML string concatenation | | hydrate | Initial client load | Claims existing SSR nodes |

The same source file compiles to different output depending on mode. In ssr mode, $effect is dropped entirely (effects don't make sense on the server). In hydrate mode, claim() calls replace createElement to reuse server-rendered nodes.

Macros

$state

Declares a reactive variable. Primitive values use subscription sets. Objects and arrays use Proxy for deep reactivity.

let count = $state(0);
count++;           // compiled to count.set(count.peek() + 1)
count = 10;        // compiled to count.set(10)

let user = $state({ name: "Rei" });
user.name = "Asuka"; // proxy handles this — no rewrite needed

$derived

A memoized value derived from other reactive state. Cached until dependencies change.

let doubled = $derived(count * 2);
// compiled to: const doubled = createMemo(() => count() * 2)
// which is another tiny shim over createEffect()

$effect

Runs a side effect that re-runs when its reactive dependencies change.

$effect(() => {
  document.title = `Count: ${count}`;
});
// compiled to: createEffect(() => { document.title = `Count: ${count()}`; })

Keyed lists

.map() with a key prop compiles to a reconciled list that surgically updates only changed items:

const items = $state([{ id: 1, name: "Rei" }, { id: 2, name: "Asuka" }]);

<ul>
  {items.map(item => (
    <li key={item.id}>{item.name}</li>
  ))}
</ul>

Compiled to reconcile() — moves, inserts, and removes DOM nodes by key without recreating unchanged elements.

Scoped CSS

CSS defined in a component file is automatically scoped with a deterministic hash:

// styles in your component file get a unique hash prefix
// .box → .box.s-a3f9b2c1
// :global(.reset) escapes scoping

Setup

Vite

// vite.config.ts
import { sigil } from "@sigil-dev/compiler/vite";

export default {
  plugins: [sigil()]
};

Bun (reccommended)

// build script
import { sigil } from "@sigil-dev/compiler/bun";

await Bun.build({
  entrypoints: ["src/index.tsx"],
  plugins: [sigil({ mode: "dom" })],
});

Babel

// babel.config.ts
import { sigilBabelPlugin } from "@sigil-dev/compiler/babel";

export default {
  plugins: [sigilBabelPlugin({ mode: "dom" })]
};

Used by

@sigil-dev/grimoire uses this compiler internally to process route files in three passes (ssr, hydrate, dom) during the build step. You can use it standalone for SPA projects via Vite, or wire it into any Babel-compatible build pipeline.