Skip to Content
Quickstart

Quick start

Three things bring people here. Pick the one that is yours.

You have…Track
a built PWFabric app, and a machine or host of your ownA — run an exported app
an idea for a block the catalog does not haveB — write a first block
nothing yet, and want an app of your ownC — build a PWFabric app from scratch

Tracks A and C use pwf, the PWFabric command line. It needs Node 22:

npm install -g @pwfabric/cli # puts `pwf` on your PATH pwf --version

The packages are at 2.2.0 on npm. They are ES modules only: a project that imports them sets "type": "module" in its package.json. Every command lists its options with pwf <command> --help; all of them are on the CLI page. (To work on PWFabric itself, clone pwfabric/pwfabric , pnpm install && pnpm build, and run node packages/cli/dist/bin.js.)

Track A — run an exported app

A pwapp runs on anything that serves files. There is no build step and no Node process: the runner is a browser ES module that reads the app’s JSON files and mounts the renderer.

1. Get the built app. A host that builds PWFabric apps can export one as a complete runnable folder, usually zipped; pwf build writes the same folder. (A pwpack on its own is the app’s source: it has no engine in it and is not runnable by itself.)

2. Unzip it. You get:

index.html ← the shell: import map, preloads, mount point _headers ← the app's Content Security Policy, for hosts that read it publish.json ← what was built: atoms, hashes, the policy assets/ ← runner, boot (calls runApp()), embed (the renderer), theme.css — content-hashed names robots.txt ← lets search engines read the app shims/ ← import-map targets the block bundles resolve against pwpack/ ← project.json, surfaces/*.receipt.json, navigation, appearance… blocks/ ← manifest.json + one hash-pinned bundle per block type engines/ ← connector engines, if the app has connections

3. Run it.

pwf run ./my-app-export # Serving ./my-app-export at http://127.0.0.1:4700/

pwf run <folder> serves any built pwapp folder, the one an export gives or the one pwf build writes. It also takes a packaged .pwapp file and serves it from memory. Page paths without a file extension are answered with index.html and a <base href="/">, so apps that use clean URLs work at any depth. --port <n> picks another port (0 for any free one) and --host <name> another interface.

The runner fetches pwpack/project.json and blocks/manifest.json, mounts into #root, and routes with #/<page> in the URL. Hash routing is the default because it works on every host without configuration.

4. Put it anywhere. pwf run is a convenience, not a requirement: the folder is plain static files, and any static file server or host serves it the same way. The shell the export writes is, in essence:

<link rel="stylesheet" href="./assets/theme.3248118d.css" /> <script type="importmap">{ "imports": { … } }</script> <link rel="modulepreload" href="./assets/runner.9094f562.js" /> <script async src="./assets/embed.4f99b147.js"></script> <div id="root"></div> <script type="module" src="./assets/boot.7838adfe.js"></script>

and the boot module calls runApp({ source: './pwpack', blocks: './blocks/', engines: './engines', renderer: './assets/embed.4f99b147.js', router: 'hash', locale: 'en' }). The renderer loads async, so nothing large holds the first paint; an app that requires sign-in does not name it at all, and the runner adds it only when it draws a page, so a visitor stopped at the gate never downloads it. The runtime files carry a hash of their content in their names, and _headers lets a host keep them for a year. The import map is the only inline script, so the app’s Content Security Policy can allow it by hash; start-up code of your own goes in a file too.

runApp() takes source, blocks, engines, router ('hash' · 'path' · 'auto'), mount and locale; every one has a default that matches the folder above, so runApp() with no arguments is equivalent. Clean URLs (router: 'path') need the host to serve index.html for every path and to declare the app’s base with <base href="/"> (the app’s sub-path, if it has one), or the shell’s relative script addresses miss on nested paths; router: 'auto' chooses them only when the shell also carries <meta name="pw-router" content="path" />.

That is the whole self-host for a static app. If the app reads or writes data it will call an API; if it gates pages behind sign-in it will talk to an issuer. What goes on the wire in each case, and what your host must provide, is in Self-hosting: the envelope, data and receipts, visitor sign-in.

Source: packages/cli/src/commands/run.ts (pwf run), packages/cli/src/dev/shell.ts (the shell and boot.js), packages/runner/src/types.ts (RunAppOptions), packages/runner/src/run-app.ts (runApp).

Track B — write a first block

You need Node 22 and a project that renders React 19 — or an empty package to try this in. The packages are ES modules: the project’s package.json needs "type": "module".

1. Install the authoring package.

pnpm add @pwfabric/authoring @pwfabric/runtime @pwfabric/contracts zod@4 react react-dom pnpm add -D typescript @types/react tsx

PWFabric uses zod 4 (^4.6.6). A project still on zod 3 stays on the 1.x packages. typescript and @types/react type-check the block; tsx runs the TypeScript examples below (npx tsx check.ts).

2. Write the block. Put it at atoms/blocks/text/customer-quote/component.tsx, the place a pwpack source tree expects it:

import { defineBlock } from '@pwfabric/authoring' import { z } from 'zod' export const CustomerQuote = defineBlock({ type: 'customer-quote', name: 'Customer quote', category: 'text', schema: z.object({ quote: z.string().min(10).max(500), author: z.string(), role: z.string().optional(), }), defaultProps: { quote: 'A great product to work with.', author: 'Jane Doe', role: 'Product Manager', }, component: ({ props }) => ( <blockquote> <p>"{props.quote}"</p> <footer>{props.author}{props.role ? `, ${props.role}` : ''}</footer> </blockquote> ), })

type is the block’s identity: 2–50 characters, kebab-case, and not one of the first-party names. defineBlock() throws on a bad type and warns on anything else it can work around.

3. Validate it. validateBlockDefinition() is the check a publish gate runs on a definition; validateBlock() checks an instance against your schema.

import { validateBlockDefinition, validateBlock, formatValidationErrors, } from '@pwfabric/authoring' import { DEFAULT_BLOCK_LAYOUT } from '@pwfabric/contracts' import { CustomerQuote } from './atoms/blocks/text/customer-quote/component' const issues = validateBlockDefinition(CustomerQuote) if (issues.some((i) => i.severity === 'error')) { throw new Error(issues.map((i) => `${i.code}: ${i.message}`).join('\n')) } const result = validateBlock( { id: 'q1', type: 'customer-quote', props: { quote: 'Too short', author: 'A. Reader' }, layout: DEFAULT_BLOCK_LAYOUT }, CustomerQuote, ) console.log(result.valid ? 'ok' : formatValidationErrors(result.errors)) // [VALIDATION_ERROR] at quote: String must contain at least 10 character(s)

4. See it render. A registry turns definitions into the component map the renderer takes:

import { createCustomBlockRegistry } from '@pwfabric/authoring' import { BlockSurfaceRenderer } from '@pwfabric/runtime' import { DEFAULT_BLOCK_LAYOUT } from '@pwfabric/contracts' import { CustomerQuote } from './atoms/blocks/text/customer-quote/component' const registry = createCustomBlockRegistry() registry.register(CustomerQuote) export function Page() { const surface = { blocks: [{ id: 'q1', type: 'customer-quote', props: { quote: 'Shipped in an afternoon.', author: 'A. Reader' }, layout: DEFAULT_BLOCK_LAYOUT }], } return <BlockSurfaceRenderer surface={surface} components={registry.getComponents()} /> }

5. Ship it. A block reaches other people’s pages as a hash-pinned ES module listed in an app’s block manifest, built from the folder you wrote in step 2. The shapes are in How a block reaches a page.

Source: packages/authoring/src/define-block.ts (defineBlock, validateBlockDefinition), packages/authoring/src/validation.ts (validateBlock, formatValidationErrors), packages/authoring/src/registry.ts (getComponents).

Track C — build a PWFabric app from scratch

You need Node 22 and pwf (see the top of this page). No account, no hosted service: everything below runs on your machine.

1. Get a foundation pack. Every app stands on a foundation pack, the pack that supplies the blocks and themes its pages are made of. Download foundation-<version>.pwpack from the releases of pwfabric/foundation , or build it in a clone: pnpm install, then node scripts/export-tgz.mjs --canonical writes it to dist/.

2. Create the app.

pwf create my-app --foundation <path>

<path> is the foundation .pwpack (or the foundation folder). (Set PWF_FOUNDATION to it once and you can leave --foundation out.) pwf create writes a canonical pwpack folder:

my-app/ ├── pwpack.json the app's id, version and pages; pins the foundation by content hash ├── app/ │ ├── plan.json what the app is for, page by page │ ├── definitions/appearance.json one of the foundation's themes │ ├── definitions/navigation.json │ └── surfaces/home.receipt.json the first page, from the foundation's blocks ├── atoms/README.md your own blocks go here ├── .gitignore keeps .pwf/ out of version control └── .pwf/packs/… a local copy of the foundation, so everything works offline

3. Work on it.

cd my-app pwf dev # pwf dev: serving … at http://127.0.0.1:<port>/

pwf dev builds the app, serves it and rebuilds on every change. Open app/surfaces/home.receipt.json, change a content prop, save: the page reloads. Add a page by writing another *.receipt.json and listing its key in pwpack.json under app.surfaceOrder. Stop it with Ctrl+C.

4. Check it.

pwf validate # @pwpack/local/my-app@0.1.0: valid (0 errors, 0 warnings; layout canonical; …) # Notes (1): # DOC_FILE atoms/README.md …

Notes are information, not problems: here, that atoms/README.md is a document, not an atom.

pwf validate checks the folder against the pwpack format and every pinned pack against its content hash. It exits 1 on any error.

5. Pack it.

pwf pack # Packed @pwpack/local/my-app@0.1.0 # file …/my-app/my-app-0.1.0.pwpack

The .pwpack is the app’s source in one deterministic archive: the same folder always gives the same bytes. It is the form you hand to someone else or import elsewhere.

6. Build it.

pwf build # built 1 page, 3 block types, 0 engines — 37/38 atoms compiled … # wrote 27 files to .pwf/out

.pwf/out/ is the runnable app, a pwapp: index.html, the runner, one compiled bundle per block type and the app’s JSON. --out <dir> writes it somewhere else.

7. Run it.

pwf run .pwf/out # Serving .pwf/out at http://127.0.0.1:4700/

Open the address. That folder is plain static files: copy it to any static host and it runs there the same way.

You just built a PWFabric application from scratch.

Three finished apps to read and copy, from a static two-page site to one with data and sign-in, are in pwfabric/examples , each with a README.

Source: packages/cli/src/commands/ (create.ts, dev.ts, validate.ts, pack.ts, build.ts, run.ts).

Next steps

  • CLI — every pwf command and option
  • Specification — the formats a pwpack and a pwapp are made of
  • Authoring — the full export surface, and factories and capabilities
  • defineBlock() — every option, and what the runtime does with each
  • Self-hosting — everything a downloaded app needs from a host
  • Licensing — what you may do with the code
Last updated on