Guide

From an empty folder to a deployed app: install, create, develop, check, build and deploy. Every terminal block on this page is real output from pragma 0.1.0, run in a fresh app.

Install

pragma is one Rust binary. It compiles, checks, serves and bundles npm packages by itself: no Vite, no esbuild, no config. You need a Rust toolchain (cargo, from rustup) to build it. Node 22 or newer is needed only when an app has .server.js files, because pragma dev, pragma serve and the Node adapter run them.

~
git clone https://github.com/leonavas/pragma
cd pragma
cargo install --path core/cli/crates/pragma-cli

~/pragma
pragma -V
pragma 0.1.0
pragma --help
pragma — HTML, CSS and JS without a framework

usage:
  pragma new <dir>                              create an app in <dir> (empty or missing)
  pragma dev [--port 5180] [--host 127.0.0.1]   dev server with live reload
  pragma build                                  build dist/ for production
  pragma check [--strict]                       check HTML, CSS, JS and budgets (--strict: warnings become errors)
  pragma serve [--port 3000] [--host 127.0.0.1] serve dist/ as in production
  pragma upgrade                                update core/ (runtime, docs, base.css) to this version

options:
  -h, --help      show this help
  -V, --version   show the version

Options take either form, --port 8080 or --port=8080. The cargo install output and the clone progress are left out above.

To update, run git pull and the same cargo install, then pragma upgrade inside each app. It makes the app's core/ (runtime, docs, base.css) match the new binary, prints every file it updated, added or removed, and never touches anything outside core/. Until then pragma check warns with app/core-outdated.

Create an app

pragma new writes a working app into an empty or missing folder: a layout, a home page with a modal, an alert and a dropdown, a 404 page, the theme, the runtime in core/ and the docs in core/docs/.

~/projects
pragma new my-app
app created in my-app (41 files)

  cd my-app
  pragma dev

The app ships an AGENTS.md (and a CLAUDE.md that includes it) with the syntax in a dozen lines, the rules the compiler enforces and a table that maps each task to one file in core/docs/. A coding agent reads that first; you can too. The docs are short on purpose: every page fits in a context window.

Your first component

A component is a folder with one .html file: an optional <script>, the markup, an optional <style>. In the script, a top-level let is state, a function is an action when an event calls it and a derived value when the markup reads it, and export let declares a prop. In the markup, {$count} puts a value in the text, @click calls a function and :disabled binds an attribute. Assigning a variable is all it takes to update the page.

routes/_components/counter/counter.html

<script>  export let label = 'Count'  export let start = 0  export let step = 1  let count = start  const atStart = () => count === start  function decrease() { count -= step }  function increase() { count += step }  function reset() { count = start }</script><div role="group" :aria-label="$label">  <span class="counter-label">{$label}</span>  <button type="button" class="btn btn-small" aria-label="Decrease" @click="decrease">−</button>  <output class="counter-value">{$count}</output>  <button type="button" class="btn btn-small" aria-label="Increase" @click="increase">+</button>  <button type="button" class="btn btn-small" @click="reset" :disabled="$atStart">Reset</button></div><style>  [data-c="counter"] { display: inline-flex; flex-wrap: wrap; align-items: center; gap: 0.5rem; }  .counter-label { color: var(--color-muted); font-size: 0.875rem; }  .counter-value { min-width: 2rem; font-family: var(--font-mono); text-align: center; font-variant-numeric: tabular-nums; }</style>

Live result

Cups of coffee 1
In your app this file is lib/components/counter/counter.html and the tag is c-counter. Here it sits next to the guide as p-counter.

Use it on any page. The build expands it in place, so its markup is in the prebuilt HTML, and its script loads only on pages that use it: a page with just this counter loads 8.9 kB of JS, runtime included.

routes/index.html
<c-counter label="Cups of coffee" start="1"></c-counter>

  • The default sets the prop's type: start="1" arrives as the number 1 because the default is 0; a bare attribute is true.
  • Props are read-only and live. let count = start copies one into state that the component can change.
  • The <style> is scoped with [data-c="counter"]; utilities from classes.md cover the rest.
  • pragma check reads the script: a name the markup uses but the script lacks is html/unknown-name, an attribute the component does not declare is html/unknown-prop, a write to a prop is js/prop-write.

Project structure

The layout is fixed, so there is nothing to configure and only one place for each thing. The files below are exactly what pragma new creates, minus core/.

my-app/
pragma.json               name, lang and budgets
AGENTS.md  CLAUDE.md      rules for coding agents
routes/
  _layout.html            header, footer, site-wide <head>; <slot> is the page
  _404.html               unknown URLs
  index.html              /         (markup, its <script> and <style>)
lib/
  components/<name>/      <c-name> for every page: modal, alert, dropdown
  state/<name>.js         stores, reached as shared.<name>
  theme.css               tokens and the few custom classes
utils/                    plain JS modules
public/                   copied as is: favicon.svg, images, fonts
core/                     runtime and docs; never edited

  • Only routes/, lib/, utils/, core/ and public/ are read. Other top-level files, like a README, are ignored.
  • A page is routes/x.html, with an optional <script> and <style> at its top level and an optional x.server.js (load, server actions, ssr). A large script can live in x.js beside it instead, never both (html/duplicate-module).
  • Anything else in routes/ must be private, with a leading underscore: _components/, _products.json, _catalog.server.js.
  • pragma.json takes exactly name (required: fallback title, log service name, Worker name), lang (default en) and budgets. Unknown keys are errors.
~/my-app
pragma check
routes/notes.md:1:1 error [app/structure] unsupported file in routes/ (static files go in public/, CSS in lib/theme.css or the component)
1 error(s), 0 warning(s)
pragma check
pragma.json:1:1 error [app/pragma-json] unknown key "budget" (use name, lang, budgets)
 1 | { "name": "guide-app", "budget": 3 }
   | ^
1 error(s), 0 warning(s)

Develop

pragma dev builds into .pragma/dev/, watches the folder and reloads every open tab on each save, over one WebSocket per tab. CSS changes swap in place without a reload. When a save breaks the build, the terminal prints the problem and the browser shows it in a full-screen overlay; pages without errors keep working, and the next good save clears it.

When the app has a .server.js, dev starts Node next to it, proxies /_data, /_action and /_otel, and restarts it when server code changes. Server logs, debug included, and every log record sent by the browser print in the same terminal.

~/my-app
pragma dev --port 5296
compiled in 4 ms
{"severityText":"INFO","body":"pragma serving at http://localhost:33227","resource":{"service.name":"my-app"}}
node running on port 33227
pragma dev at http://127.0.0.1:5296
changed: routes/about.html
routes/about.html:4:4 error [html/on-inline] inline onclick is not allowed; use @<event>="action"
 4 | <p onclick="track()">Built with pragma.</p>
   |    ^
1 error(s), 0 warning(s)
changed: routes/about.html
compiled in 3 ms
changed: routes/orders/index.server.js
compiled in 2 ms
{"severityText":"INFO","body":"pragma serving at http://localhost:43459","resource":{"service.name":"my-app"}}
node restarted on port 43459
{"severityText":"DEBUG","body":"orders requested","traceId":"e02d1c33…","resource":{"service.name":"my-app"}}
{"severityText":"INFO","body":"orders listed","attributes":{"orders.count":2},"traceId":"e02d1c33…"}
{"severityText":"INFO","body":"GET /orders","attributes":{"http.request.method":"GET","url.path":"/_data/orders","http.response.status_code":200,"http.route":"/orders"}}

Log lines are shortened here; the full records, with timestamps and span ids, are on the logs page. In dev, budgets only warn, and the browser throws on mistakes that production tolerates: an unknown action, a duplicate <for> key, a path that does not exist.

Check

pragma check runs a full production build into a temporary folder and reports every problem as file:line:column severity [rule] message, with a code frame and the fix. Accessibility findings are warnings; --strict turns them into errors and fails on any warning. The bar for finishing is pragma check --strict with zero of both.

~/my-app
pragma check
routes/broken.html:6:11 error [js/vague-name] name `tmp` does not say what it is or does; use a self-explanatory name (e.g. `product`, `totalItems`, `addToCart`)
 6 |     const tmp = query.trim()
   |           ^
routes/broken.html:7:5 error [js/console] `console` is not allowed; use `log` (`import { log } from 'pragma'`, or core/log.js outside scripts)
 7 |     console.log(tmp)
   |     ^
routes/broken.html:12:1 warning [a11y/img-alt] <img> without alt; use alt="" if the image is decorative
 12 | <img src="/chart.png">
    | ^
routes/broken.html:13:1 warning [a11y/accessible-name] <button> without an accessible name: add text, {path} or aria-label
 13 | <button @click="refresh"></button>
    | ^
routes/broken.html:14:1 warning [a11y/label] <input> without label: use <label for>, wrap it in a <label> or add aria-label
 14 | <input type="text" :model="$query">
    | ^
routes/broken.html:15:1 warning [a11y/heading] skipped heading level: <h1> followed by <h3>
 15 | <h3 class="w-[37px]" :class="$tone">Recent</h3>
    | ^
routes/broken.html:15:5 error [css/arbitrary-value] arbitrary value "w-[37px]" is not supported; use a utility from core/docs/classes.md or add a class in lib/theme.css
 15 | <h3 class="w-[37px]" :class="$tone">Recent</h3>
    |     ^
routes/broken.html:15:22 error [html/class] :class is not allowed: write static classes in class="…" and toggle each one with .name="path" (e.g. .text-warning-700="$warn")
 15 | <h3 class="w-[37px]" :class="$tone">Recent</h3>
    |                      ^
routes/broken.html:15:22 error [html/unknown-name] $tone is not declared in the script of routes/broken.html: add `let tone = …` (state), `export let tone = …` (prop) or `function tone() { … }`
 15 | <h3 class="w-[37px]" :class="$tone">Recent</h3>
    |                      ^
routes/broken.html:16:4 error [html/interpolation] {{ }} is not pragma syntax: write {path} in text and attributes (e.g. <p>Hi {$name}</p>, alt="Photo of {p.name}"); inside <code> or <pre> it is shown as text
 16 | <p>{{ $query }}</p>
    |    ^
routes/broken.html:17:4 error [html/text-removed] `:text` was removed: write {$total} inside the element (e.g. <p>{$name}</p>)
 17 | <p :text="$total"></p>
    |    ^
routes/broken.html:19:3 error [html/head] <meta> belongs in <head>: write it at the top level of the page fragment (or in the layout <head>)
 19 |   <meta name="robots" content="noindex">
    |   ^
8 error(s), 4 warning(s)
pragma check --strict
… the same twelve findings, all reported as errors
12 error(s), 0 warning(s)

The rules form a closed list. Anything outside the syntax is an error with a pointer to the fix, so an agent cannot quietly drift into another framework's habits.

  • JS: js/syntax, js/comment, js/console, js/vague-name, js/html-in-js (no innerHTML or createElement), js/jsdoc-types, js/import, and the script rules: js/component-script (no var, no top-level await, export only for props), js/prop-write, js/const-state (a mutated const the markup reads), js/store-import (stores only through shared) and js/legacy-api (the old state(ctx) API, with the migration).
  • HTML: html/syntax (close every non-void tag), html/comment, html/script, html/duplicate-module (a <script> and an x.js for the same file), html/style-inline, html/on-inline, html/legacy-syntax, html/unknown-directive, html/invalid-path, html/invalid-root, the block rules (html/block, html/for-without-key, html/misplaced-else…), html/unknown-name, html/unknown-prop, html/component, html/unknown-component, html/layout, html/title, html/class (no :class), html/text-removed (no :text), html/interpolation (no {{ }} or ${ } outside <code>/<pre>), html/data-attribute (no hand-written data-*) and html/head (<meta> and <link> only at the top of a page or in the layout head). html/unknown-directive also names the pragma form for Vue, Alpine, Svelte, Angular and React attributes.
  • CSS: css/syntax, css/comment, css/unknown-class (only the utilities in classes.md and classes your CSS defines), css/arbitrary-value.
  • App: app/structure, app/route-conflict, app/package, app/pragma-json, app/budget, and the warning app/core-outdated when core/ differs from the installed binary.
  • Accessibility, checked on the expanded page with components inlined: img-alt, accessible-name, label, dialog-name, click-non-interactive, heading, single-h1, tabindex, duplicate-id, iframe-title, a-no-href. A bound attribute counts: :aria-label satisfies aria-label.

Performance budgets

Budgets are gzip kilobytes in pragma.json, enforced by check and build: initialJsKb is all JS a page loads, runtime included; routeJsKb is the page's own JS outside core/, npm packages included; cssKb is the global stylesheet. An omitted key is not checked. Exceeding one is an error in production builds and a warning in dev.

~/my-app
cat pragma.json
{
  "name": "my-app",
  "lang": "en",
  "budgets": { "initialJsKb": 9, "routeJsKb": 10, "cssKb": 15 }
}
pragma check --strict
pragma.json:4:1 error [app/budget] initialJsKb exceeded in /: 10.0 kB gzip > 9 kB
 4 |   "budgets": { "initialJsKb": 9, "routeJsKb": 10, "cssKb": 15 }
   | ^
1 error(s), 0 warning(s)

The starter budgets are 15, 10 and 15. A page with no script of its own costs 8.7 kB gzip, all of it runtime, so the budget is real room for your code. The fix for a budget error is smaller code, never a bigger number. What the build does so that you rarely hit one:

  • Every route is prebuilt HTML, and a page with a load starts its data fetch from an inline script in <head>, before any module runs.
  • Exactly the modules a page imports get a modulepreload. Modules are minified and hashed one by one; there is no app bundle.
  • The CSS contains only the classes the app uses.
  • Links prefetch on hover, focus or when visible; navigations use view transitions.
  • HTML is served no-cache, /assets/ as immutable, both brotli or gzip compressed.
  • Code needed only after a click goes behind await import() in the action: not preloaded, not in the budget. See lazy packages.

Build

pragma build writes dist/ and prints the JS each page loads and the CSS size, gzip. The same binary bundles npm packages with rolldown, so a build with dependencies needs nothing else either.

~/my-app
pragma build
page      JS gzip
/         10.0 KB
/about     8.7 KB
/orders    8.7 KB
CSS        4.1 KB
3 page(s), with server
dist/ built in 6 ms
find dist -type f -not -path "*/assets/*" -not -path "*/server/core/*"
dist/client/index.html
dist/client/about.html
dist/client/orders/index.html
dist/client/_404.html
dist/client/favicon.svg
dist/client/_pragma/manifest.json
dist/server/worker.js
dist/server/node.mjs
dist/server/wrangler.jsonc
dist/server/package.json
dist/server/routes/orders/index.server.js

  • dist/client/: one HTML file per route (a param route keeps its name, blog/[slug].html), _404.html, hashed assets/, the files from public/ and _pragma/manifest.json.
  • dist/server/: worker.js (a fetch handler with the route table), node.mjs (a Node adapter around it), wrangler.jsonc, and your .server.js files copied unbundled with their relative imports.
  • dist/templates/<route>.json: only for routes with ssr = true.

Serve and deploy

pragma serve is a local preview of production: it serves dist/ with precompressed brotli and gzip, ETags and the production cache headers, and starts dist/server/node.mjs when there is one.

~/my-app
pragma serve --port 5294
files compressed in 18 ms
{"severityText":"INFO","body":"pragma serving at http://localhost:38487","resource":{"service.name":"my-app"}}
node running on port 38487
pragma serve at http://127.0.0.1:5294
curl -sD - -o /dev/null -H "accept-encoding: br" http://127.0.0.1:5294/orders
HTTP/1.1 200 OK
content-type: text/html; charset=utf-8
cache-control: no-cache
content-length: 778
etag: W/"8a3-18e95340ec2094a1"
vary: accept-encoding
content-encoding: br
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:5294/does-not-exist
404

Then pick a target. All three ship the same dist/client/.

  • Static hosting, for apps without .server.js: upload dist/client/. The host must serve /about from about.html, a param route such as /blog/x from blog/[slug].html, and unknown paths from _404.html with status 404. Generic static hosts usually cannot do param routes, and without a /_otel endpoint the client stops sending logs after the first 404 or 405.
  • Node: copy dist/ and node_modules, then run the adapter. It serves the files with the right types and cache headers, resolves param routes through the manifest, renders SSR pages and the 404 page, and answers /_data, /_action and /_otel. Node finds node_modules by walking up from dist/server/.
  • Cloudflare Workers: the generated wrangler.jsonc points main at worker.js and the assets binding at ../client; wrangler bundles the server code on deploy. Workers have no filesystem, and node:* imports in .server.js need "compatibility_flags": ["nodejs_compat"] added to that file.
deploy
PORT=8080 node dist/server/node.mjs
{"severityText":"INFO","body":"pragma serving at http://localhost:8080","attributes":{"server.port":8080}}
cat dist/server/wrangler.jsonc
{
  "name": "my-app",
  "main": "worker.js",
  "compatibility_date": "2025-11-01",
  "assets": {
    "directory": "../client",
    "binding": "ASSETS",
    "run_worker_first": true
  }
}
npx wrangler deploy --config dist/server/wrangler.jsonc

Under the hood

Nothing here needs configuring, but it helps when you read the built HTML or debug a deploy.

  • The generated <head> comes in this order: charset, viewport, <title>, the layout's head tags (a page's own <meta> and <link> replace the layout's tag with the same name), the theme script when used, the stylesheet, the inline /_data fetch when the page has a load, the modulepreloads, the route JSON and the boot module.
  • The route JSON, a <script> with id="pragma-route", tells the runtime what to start:
    {"pattern":"/orders","page":null,"components":{},"stores":{},"loader":true,"ssr":false}
  • /_pragma/manifest.json lists every route with its HTML file, modules, loader and SSR flag. The client router and the Node adapter both read it.
  • Data travels as GET /_data/<path> and server actions as POST /_action/<path>/<name>, both with a traceparent header.
  • Not in v0: static generation with data, nested layouts, catch-all routes ([...rest]), per-route CSS, i18n and Speculation Rules.

Next: the examples show every feature running, with its source.