BackflipHTML

BackflipHTML is an HTML templating system that supports generating output in multiple languages. You write HTML with special b-* directive attributes and {{ expression }} interpolations using a subset of JavaScript, and the system compiles it into JS or PHP files. A lightweight runtime generates HTML from these outputs.

(For now only JS and PHP are supported. Go is coming later. Other languages can be supported fairly easily.)

How it works

HTML template string
        │
        ▼
  [ compiler/ ]  ──── parses HTML, recognizes b-* directives,
                       interprets expressions via backcode.ts
        │
        ▼
   RootTNode AST (expressions as parsed AST objects)
        │
        ├─────────────────────────────┐
        ▼                             ▼
  [ compiler/generate/js/ ]     [ compiler/generate/php/ ]
  converts TNode tree →         converts TNode tree →
  JS source string              PHP source file
        │                                 │
        ▼                                 ▼
  Emitted JS module             Emitted .php file
  (RNode-shaped object)         (array of node trees)
        │                                 │
        ▼                                 ▼
  [ runtime/js/ ]               [ runtime/php/ ]
  walks tree + JS context       walks tree + PHP array context
  → Generator<string> chunks    → Generator chunks
    or collected HTML string      or collected HTML string

The compile step only needs to run once per template. The resulting module can be cached and reused, with only the lightweight runtime render pass running per request.

Subprojects

compiler/

Parses HTML templates into a language-agnostic AST and generates JS or PHP source files from it.

runtime/

Streaming HTML renderers in JS and PHP that execute compiled templates with a data context.

Developer Tooling Subprojects

assets/

Handles the discovery, tracking, and reporting of static assets referenced in BackflipHTML templates and CSS.

css/

Matches CSS selectors to template elements, accounting for partials, conditionals, and dynamic attributes. Used by the LSP.

lsp/

Language Server providing diagnostics, go-to-definition, find references, hover, and document symbols for templates and CSS.

preview/

Local dev server that renders partials with auto-generated mock data and live reload.

vscode-backflip/

VSCode extension providing syntax highlighting, language server integration, and a preview panel for templates.

Documentation

• Directives reference — all b-* directives and the expression language
• Partials — defining, including, and composing partials with slots
• Assets — configuring and referencing static assets like images and styles
• CLI — compiling templates from the command line
• Configuration — backflip.json reference
• JS runtime — JavaScript runtime API and usage
• PHP runtime — PHP runtime API and usage
• Dual-runtime support — using from Deno vs Node.js

Developer Tooling Docs

• Preview — preview system, programmatic API, VSCode integration

Testing

From the repo root, run compiler, runtime, preview, and integration tests via Deno:

deno task test

Integration Tests test/

End-to-end integration tests for the full compile → generate → render pipeline.

PHP integration tests require php in PATH. CLI tests spawn deno subprocesses.

LSP and CSS

The LSP and CSS packages have their own test suites — see their READMEs for details.