Skip to content

cli.md

Latest commit

 

History

History
124 lines (84 loc) · 4.19 KB

cli.md

File metadata and controls

124 lines (84 loc) · 4.19 KB
Raw

BackflipHTML CLI

Installation

Run the CLI directly from the GitHub repo using Deno:

deno run --allow-read --allow-write https://raw.githubusercontent.com/teleclimber/BackflipHTML/main/cli.ts

No local installation or compilation is needed — Deno fetches and caches the module automatically.

To pin a specific tagged version or commit hash, replace main in the URL:

# Use a tagged version
deno run --allow-read --allow-write https://raw.githubusercontent.com/teleclimber/BackflipHTML/v0.1.0/cli.ts

# Use a specific commit hash
deno run --allow-read --allow-write https://raw.githubusercontent.com/teleclimber/BackflipHTML/abc1234/cli.ts

For convenience you can create a shell alias:

alias backflip="deno run --allow-read --allow-write https://raw.githubusercontent.com/teleclimber/BackflipHTML/main/cli.ts"

Generate mode

Compile HTML templates and write output files:

backflip <input-dir> <output-dir> --lang <js|php|dom-patch>
  • <input-dir> — directory of .html template files (scanned recursively)
  • <output-dir> — must be empty (when provided via CLI); output files mirror the input directory structure
  • --lang js — generate JavaScript modules (.js)
  • --lang php — generate PHP files (.php)
  • --lang dom-patch — generate browser-side patcher classes (.js) for custom-element partials with reactive attributes (see Configuration → dom-patch)

Examples:

# Generate JS files
backflip ./templates ./out --lang js

# Generate PHP files
backflip ./templates ./out --lang php

# Generate dom-patch classes
backflip ./templates ./out --lang dom-patch

When the output directory is specified via CLI arguments, it must be empty before running. When the output directory comes from backflip.json, it is automatically emptied before writing. The input hierarchy is preserved, with .html extensions replaced by .js or .php.

When a dom-patch output produces scripts but its output directory is not covered by any asset prefix, the build prints a non-fatal warning and the generated scripts are not auto-included by the renderer:

warning: dom-patch output "<path>" is not covered by an asset prefix; generated scripts will not be auto-included. Add an asset entry whose directory contains this output dir.

When a reactive partial produces dom-patch code but its definition has no b-script, nothing imports the generated module — so the component never registers. The build warns:

warning: <my-widget> has generated dom-patch code but no b-script; its client module won't be auto-injected. Add b-script="@asset/..." on the definition pointing at the hand-coded web component.

See Configuration → dom-patch for how the generated module's URL is derived, and Partials → Client script for b-script.

Check mode

Validate templates for compile errors without writing any output:

backflip <input-dir> --check [--json]
  • --check — report errors only, no files written
  • --json — format errors as JSON (useful for editor integrations)

Examples:

# Plain text error output
backflip ./templates --check

# JSON error output
backflip ./templates --check --json
# => { "errors": [] }
# => { "errors": ["In \"blog/post.html\": ..."] }

Asset reporting mode

Scan templates for asset references and report on unused assets:

backflip <input-dir> --assets-report [--unused-only] [--json]
  • --assets-report — show asset usage report (exits 1 if unused assets are found)
  • --unused-only — only list unused assets (implies --assets-report)
  • --json — output the report as JSON

Note: Requires asset directories to be configured in backflip.json.

Examples:

# Plain text summary and list
backflip --assets-report

# Fail CI if there are dead assets, output JSON for parsing
backflip --assets-report --unused-only --json

Exit codes

Code Meaning
0 Success (generate: files written; check: no errors)
1 Error (compile error, invalid arguments, or non-empty output directory)