Vite setup · Preact Loom

Prepare the compiler once

Install the pinned toolchain and build the release WASM compiler. Vite loads this Node-targeted artifact only in its configuration process.

Terminal

pnpm install
pnpm build:wasm

Add the graph plugin

The plugin snapshots source files below sourceRoot, asks the graph compiler for an exact-or-external result, and serves the emitted modules through Vite's virtual-module convention.

vite.config.mjs

import { createRequire } from "node:module";
import { resolve } from "node:path";
import { preactLoom } from "./integrations/vite-plugin.mjs";

const require = createRequire(import.meta.url);
const { compile_module_graph: compileModuleGraph } = require(
  resolve("target/wasm-node/compiler.js")
);

export default {
  plugins: [
    preactLoom({
      compileModuleGraph,
      entry: "src/App.tsx",
      runtimePath: "runtime/runtime.js",
      reportPath: ".preact-loom/eligibility.json"
    })
  ]
};

No compiler payload. The virtual entry imports generated JavaScript and runtime helpers. WASM stays in the Vite process.

Mount the virtual application

Author normal Preact-shaped TSX, then import the stable virtual entry from the browser bootstrap.

src/App.tsx

import { useState } from "preact/hooks";

export function App() {
  const [count, setCount] = useState(0);
  return (
    <button onClick={() => setCount(count + 1)}>
      Compiled clicks: {count}
    </button>
  );
}

src/main.js

import { createApp } from "virtual:preact-loom/app";

createApp(document).render(
  document.querySelector("#app")
);

Run the checked example

pnpm exec vite --config examples/vite/vite.config.mjs

Make eligibility visible

Every build can persist a stable report instead of asking developers to infer compilation from bundle output. It records direct modules, fallback selections, reasons, template-node counts, binding counts, and dependency boundaries.

.preact-loom/eligibility.json

{
  "schemaVersion": 1,
  "summary": {
    "modules": 1,
    "directModules": 1,
    "fallbackModules": 0,
    "directPercent": 100
  },
  "modules": [{
    "inputPath": "src/App.tsx",
    "selection": "direct",
    "templateNodes": 2,
    "bindings": 2
  }]
}

Know where Vite stops

DirectProven TSX graphs receive direct DOM, string rendering, and hydration entrypoints.

ExternalResolvable unsupported graphs preserve authored behavior through real Preact.

ReloadSource changes currently rebuild the graph and request a full page reload; fine-grained HMR is not yet claimed.

PackageThe integration is validated from this repository, but no stable npm package is published yet.