Recast Core Concepts

Recast is a string-based HTML template engine designed for server-side rendering. It provides a powerful and type-safe way to build HTML templates with modern developer experience.

Recast is part of the Reface ecosystem - a collection of tools and libraries for building modern web applications. While it can be used standalone, it works best with other Reface components.

Key Features

• Server-First: Optimized for server-side rendering with minimal client-side JavaScript

• Type Safety: Full TypeScript support across all APIs

• Performance: Efficient template reuse and minimal runtime overhead

• Developer Experience: Modern APIs with excellent IDE support

• Extensibility: Plugin system for custom functionality

• Security: Built-in XSS protection and content security

Core Systems

1. JSX - High-level component syntax

   1const Button = component((props: Props) => (

   2 ​<button class={props.class}>{props.children}</button>

   3));

   • React-like syntax

   • TypeScript integration

   • Component composition

   • Props validation

2. HTML API - Low-level HTML string creation

   1// Template literal

   2html`<div class="box">${content}</div>`;

   3

   4// Function component

   5const Button = (props: Props, children: string) => {

   6 ​return html`<button class="btn">${children}</button>`;

   7};

   • Safe HTML strings

   • Function components

   • Attribute helpers

   • XSS protection

3. Template API - Core API for creating and manipulating HTML elements

   1const template = div({ class: "box" })`${content}`;

   • Prebuilt HTML tags

   • Template factory

   • Chainable API

   • Security features

4. Node System - Internal representation and render pipeline

   1const node = createElement("div", { class: "box" }, [content]);

   • Node types (Text, HTML, Element, Component)

   • Template to Node conversion

   • Node processing and normalization

   • Metadata handling

5. Component System - Reusable elements with unique instance IDs

   1const Button = component((props: Props) => (

   2 ​<button class="btn">{props.children}</button>

   3));

   • ComponentTemplate creation and lifecycle

   • Instance ID management

   • Client-side integration

   • Props validation

6. Styling System - Built-in CSS-in-JS solution

   1const StyledDiv = styled.div/*css*/ `

   2 ​& {

   3 ​ ​color: red;

   4 ​}

   5`;

   • Styled components

   • CSS processing and scoping

   • Style deduplication

   • Theme support

7. Slots System - Content distribution mechanism

   1const Layout = component(() => (

   2 ​<div>

   3 ​ ​<slot name="header" />

   4 ​ ​<slot />

   5 ​</div>

   6));

   • Named slots

   • Content providers

   • Slot strategies

   • Built-in slots

8. Plugin System - Extensible render pipeline

   1const plugin = createPlugin({

   2 ​name: "custom",

   3 ​transform: (node) => node,

   4});

   • Plugin architecture

   • Built-in plugins

   • Custom plugins

   • Plugin lifecycle

9. Render API - Transform NodeProxies into HTML

   1const html = await render(template, {

   2 ​plugins: [plugin],

   3});

   • Render pipeline

   • Node transformation

   • HTML generation

   • Optimization strategies

10. Test Utils - Testing helpers

• Template testing

• Component testing

• Render testing

• Snapshot testing

11. Integrations - Third-party integrations

• HTMX support

• Other integrations

See each section for detailed documentation.