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 -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/.
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
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.
<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 is0; a bare attribute istrue. - Props are read-only and live.
let count = startcopies one into state that the component can change. - The
<style>is scoped with[data-c="counter"]; utilities fromclasses.mdcover the rest. pragma checkreads the script: a name the markup uses but the script lacks ishtml/unknown-name, an attribute the component does not declare ishtml/unknown-prop, a write to a prop isjs/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/.
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/andpublic/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 optionalx.server.js(load, server actions,ssr). A large script can live inx.jsbeside 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.jsontakes exactlyname(required: fallback title, log service name, Worker name),lang(defaulten) andbudgets. Unknown keys are errors.
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.
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.
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(noinnerHTMLorcreateElement),js/jsdoc-types,js/import, and the script rules:js/component-script(novar, no top-levelawait,exportonly for props),js/prop-write,js/const-state(a mutatedconstthe markup reads),js/store-import(stores only throughshared) andjs/legacy-api(the oldstate(ctx)API, with the migration). - HTML:
html/syntax(close every non-void tag),html/comment,html/script,html/duplicate-module(a<script>and anx.jsfor 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-writtendata-*) andhtml/head(<meta>and<link>only at the top of a page or in the layout head).html/unknown-directivealso names the pragma form for Vue, Alpine, Svelte, Angular and React attributes. - CSS:
css/syntax,css/comment,css/unknown-class(only the utilities inclasses.mdand classes your CSS defines),css/arbitrary-value. - App:
app/structure,app/route-conflict,app/package,app/pragma-json,app/budget, and the warningapp/core-outdatedwhencore/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-labelsatisfiesaria-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.
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
loadstarts 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/asimmutable, 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.
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, hashedassets/, the files frompublic/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.jsfiles copied unbundled with their relative imports.dist/templates/<route>.json: only for routes withssr = 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.
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: uploaddist/client/. The host must serve/aboutfromabout.html, a param route such as/blog/xfromblog/[slug].html, and unknown paths from_404.htmlwith status 404. Generic static hosts usually cannot do param routes, and without a/_otelendpoint the client stops sending logs after the first 404 or 405. - Node: copy
dist/andnode_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,/_actionand/_otel. Node findsnode_modulesby walking up fromdist/server/. - Cloudflare Workers: the generated
wrangler.jsoncpointsmainatworker.jsand the assets binding at../client; wrangler bundles the server code on deploy. Workers have no filesystem, andnode:*imports in.server.jsneed"compatibility_flags": ["nodejs_compat"]added to that file.
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/_datafetch when the page has aload, the modulepreloads, the route JSON and the boot module. - The route JSON, a
<script>withid="pragma-route", tells the runtime what to start:{"pattern":"/orders","page":null,"components":{},"stores":{},"loader":true,"ssr":false} /_pragma/manifest.jsonlists 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 asPOST /_action/<path>/<name>, both with atraceparentheader. - 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.