@alpaca-headless/dynamic-renderings-engine

Compiles Alpaca Headless dynamic renderings and runs them, inside the rendering host's own process:

• Compile threads (dist/compile-thread.mjs): esbuild-wasm bundles a rendering with an import allowlist that never touches the file system; Tailwind compiles its classes against the host's theme and the tenant's tokens; the stylesheet policy scopes the result to the rendering. Nothing here runs rendering code. A queue, a deadline that ends the thread, and a heap limit bound them.
• Render threads (dist/render-thread.mjs): one per active tenant, each with its own QuickJS (WebAssembly) instance running dist/runtime.js. Rendering code sees only that runtime and returns a JSON render tree. QuickJS's memory limit and interrupt deadline bound every call; the pool's watchdog ends a thread that does not stop in time.

A rendering may have client code, which its code imports as ./client. The compiler builds it twice: a minified browser ES module whose react, react/jsx-runtime and react-dom imports resolve to globalThis.__alpaca_dynamic_react ({ React, ReactDOM, jsxRuntime }, set by the host), and a CommonJS module for the render threads. There, every client component the server code renders becomes an island node with a first paint: the component rendered once by react-dom/server inside QuickJS (hooks start at their initial values, effects and event handlers do not run) and parsed back into render nodes, with an islandChildren node where its children go. Client code only ever runs in QuickJS or, as the browser module, in the page.

The main entry (dist/engine.mjs) only supervises the threads, so the host's main thread loads neither the compiler nor QuickJS. It is used by @alpaca-headless/dynamic-renderings; heads do not call it directly, but must load it unbundled (withDynamicRenderings does that for Next.js).

import { createEngine } from "@alpaca-headless/dynamic-renderings-engine";
const engine = createEngine({ renderThreads: 4, compileThreads: 2 });
const compiled = await engine.compile({ renderingId, code, clientCode, themeCss, themeTokens });
const module = { server: compiled.compiledServer, client: compiled.compiledClientNode, clientExports: compiled.clientExports };
const [result] = await engine.renderPage({ tenant, components: [{ key, buildId, dto }], sources: { [buildId]: module } });
await engine.close();

The entry and the threads bundle everything they run into dist/, with the licences in THIRD_PARTY_LICENSES. The package also owns the render protocol (/protocol) and the stylesheet policy (/css-policy); the stylesheet policy is shipped unbundled and needs postcss at runtime. It does not depend on the host package, the Alpaca SDK or Next.js. Build and test (from Headless/):

npm run test --workspace=@alpaca-headless/dynamic-renderings-engine