R
Reface
Documentation

Main Concepts

System Architecture

example.undefined
 1┌────────────────────────────────────────────────────────────────┐
 2│                           Reface                               │
 3│                                                                │
 4│  ┌─────────────┐          ┌────────────┐                       │
 5│  │    Deno     │          │   Router   │                       │
 6│  │   Server    │─────────▶│   System   │                       │
 7│  └─────────────┘          └────────────┘                       │
 8│         │                       │                              │
 9│         ▼                       ▼                              │
10│  ┌─────────────┐          ┌────────────┐                       │
11│  │   Static    │          │  Layouts   │                       │
12│  │   Files     │          │            │                       │
13│  └─────────────┘          └────────────┘                       │
14│                                │                               │
15│                                ▼                               │
16│  ┌─────────────────────────────────────────────────────┐       │
17│  │                    RefaceComposer                   │       │
18│  │                                                     │       │
19│  │    ┌──────────┐    ┌─────────────────────────┐      │       │
20│  │    │  Plugin  │───▶│     Template Process    │      │       │
21│  │    │  System  │    │                         │      │       │
22│  │    └──────────┘    │  1. createTemplateFactory      │       │
23│  │         │          │     ↓                   │      │       │
24│  │         │          │  2. createTemplate      │      │       │
25│  │         │          │     ↓                   │      │       │
26│  │         └─────────▶│  3. Template(attrs)     │      │       │
27│  │                    │     ↓                   │      │       │
28│  │                    │  4. Template`content`   │      │       │
29│  │                    │     ↓                   │      │       │
30│  │                    │  5. HTML Output         │      │       │
31│  │                    └─────────────────────────┘      │       │
32│  └─────────────────────────────────────────────────────┘       │
33└────────────────────────────────────────────────────────────────┘

Core Concepts

1. Template System

The template system is built on a chain of transformations, with plugins able to hook into each step:

Two main ways to work with templates:

  1. Attributes - via function call:

example.typescripttypescript
1div({ class: "container", id: "main" });

  1. Content - via template literals:

example.typescripttypescript
1div`Hello world`;

2. Component Architecture

Components in Reface are functions that create and return templates. They can be created in two ways:

  1. Elements API - native approach

  2. JSX - developer-friendly wrapper

Both approaches are translated into the same Template API calls.

3. Plugin System

Plugins extend template capabilities through a transformation system:

example.typescripttypescript
1interface TemplatePlugin {
2  ​// Transform during creation
3  ​create?: (template: Template) => Template;
4
5  ​// Transform during rendering
6  ​render?: (html: string) => string;
7}

4. Islands Architecture

Islands Architecture enables interactive components without excessive JavaScript:

  1. Partials - components with HTMX updates

  2. Islands - isolated micro-applications with RPC

example.undefined
1Server ←   HTMX/RPC ←   Island Component
2  ​↓                          ↓
3Static HTML        Isolated Interactivity

Framework vs Core

  1. RefaceComposer (Core)

    • Basic template engine

    • Plugin system

    • HTML rendering

  2. Reface (Framework)

    • Ready-to-use ecosystem

    • Routing and layouts

    • Islands Architecture

    • Built-in plugins

Best Practices

  1. Template Composition

    • Use components for reusability

    • Mix Elements API and JSX where appropriate

    • Keep template nesting manageable

  2. Performance

    • Minimize JavaScript usage

    • Use HTMX for simple updates

    • Islands only for complex interactivity

  3. Type Safety

    • Define interfaces for props

    • Use TypeScript for components

    • Validate types in templates