@weave-framework/cli

The Weave CLI — weave build (add --ssg for static generation), weave dev (watch + live-reload), weave check, weave add component, weave routes, weave merge, weave migrate, weave mcp.

Part of Weave — a fine-grained reactive, signal-native UI framework: no Virtual DOM, zero third-party runtime dependencies.

npm install -D @weave-framework/cli

Commands

| Command | What it does | |---------|--------------| | weave build | Bundle the app for production. --ssg also prerenders every route to HTML. | | weave dev | Dev server: watch, rebuild, live-reload. After each rebuild it runs weave check and paints the result into the page (--no-check turns that off). --port <n> wins over the config's dev.port; --devtools shows the reactive graph in the page; --state <name> opens the app in a state saved from that panel; --keep-state carries the named signals across each live reload. | | weave check | Type-check the project, templates included, and report template mistakes that compile clean but fail silently. --fix repairs the ones with exactly one right answer; --impact <file> lists what renders a component. | | weave add component <Name> | Write a new component — .ts, .html and a stylesheet in your styleLang — into its own folder next to the root component, where a <Name /> tag in the root template resolves it with no import. --dir and --style css\|scss\|sass\|none override the defaults; an existing file stops it before anything is written. | | weave routes | Regenerate the file-based route module from routesDir. | | weave merge | A git merge driver for templates. --install (once per clone) registers it, and from then on two people editing one template stop colliding over changes that touch different nodes. | | weave migrate | Assisted migration of an existing Angular app into this one. Reads your source project, writes a plan, then the converted code. | | weave mcp | Start the Weave MCP server over stdio, for MCP-capable AI editors. |

usage: weave <build|dev|check|add|routes|migrate|mcp> [entry|paths…] [--config file] [--out dir]
             [--serve dir] [--port n] [--no-minify] [--eager] [--ssg] [--fix]

weave --help (or -h, or no command) prints the full help; weave dev steps to the next free port when the one it wants is taken; and a finished weave build lists what it emitted, with sizes.

When the output is captured rather than shown — an MSBuild step, a CI runner, a redirect to a file — and the capturing process is on Windows, the CLI's decoration (arrows, dashes, ticks) drops to plain ASCII, because a captured log there is decoded with the console's OEM code page and → comes out as Cyrillic. A terminal, and a pipe on Linux or macOS, are unchanged. WEAVE_ASCII=1 forces the ASCII form anywhere, WEAVE_UNICODE=1 keeps the real characters even when captured, and NO_COLOR turns off ANSI colour.

Named app states, and merging templates by their tree

weave dev --devtools puts the DevTools panel in the page. Its States tab saves the screen you are looking at to .weave/states/<name>.json — plain JSON, so commit it and the team has that screen — and weave dev --state <name> opens the app already in it. A state is exactly the values of the signals you named; nothing is predicted, and none of it is reachable from a production build.

weave merge --install registers a git merge driver for *.html / *.weave. Git's own merge still runs first and its clean results are used untouched, so installing it can add resolutions but never change one you already had; on the files git could not merge, the template is read as a tree, and changes to different nodes stop being a conflict. The same node changed two ways still is one.

weave check also reports the template mistakes that compile clean and fail silently — a listener bound as a plain attribute, a misspelled DOM event or block keyword, an unknown binding prefix — each at its own line in the template file. They are warnings, so they do not fail the command. weave check --fix applies the ones with exactly one right answer and re-checks; a rule that could plausibly mean more than one thing never guesses.

Configuration

A weave.config.ts in the working directory (or --config <file>) switches build and dev into the config-driven pipeline; without one, the flags drive a single-entry build.

// weave.config.ts
import { defineConfig } from '@weave-framework/cli';

export default defineConfig({
  root: 'src/app/app',     // the root component — Weave generates the bootstrap
  index: 'src/index.html', // HTML shell; Weave injects the script + styles
  publicDir: 'public',     // static assets copied into the build
  outDir: 'dist',
  routesDir: 'src/pages',  // opt into file-based routing
  styleLang: 'scss',
  base: '/my-app/',        // only when the app is not served from the domain root
  dev: { port: 5173, proxy: { '/api': 'http://localhost:3000' } },
});

Also available: mount (selector, default #app), entry (single-entry mode instead of root), styles, and build: { minify }. An explicit --out overrides the config's outDir.

Deploying

base is what makes a sub-path deploy work — a GitHub Pages project site, a reverse proxy, /docs/. Every URL the framework injects carries it, weave dev answers under it, and the router adopts it as its basename, so <Link to="/about"> is still written as /about and resolves to /my-app/about.

The injected <script> and <link> also carry a content marker (/main.js?v=1a2b3c), so a CDN cannot answer fresh HTML with a stale bundle. An app with routesDir additionally gets a 404.html — a copy of the shell, which is what a static host serves for an unknown path and therefore what makes a deep-link refresh work where rewrite rules are not available.

Static generation

weave build --ssg renders every route to real HTML at build time — painted on arrival, crawlable, and served as plain files with no server in the request path. Routes are derived automatically from routesDir (override with ssg.routes) and each page is its own chunk, so a reader downloads the page they opened rather than your whole site.

npx weave build --ssg

--ssg needs a config with a root component — that's what it renders headlessly.

Add ssg: { resume: true } to weave.config.ts and the browser resumes that HTML instead of rebuilding it: the build snapshots the reactive graph into the page, the client re-attaches the existing DOM to it, and setup() never runs on the client.

export default defineConfig({
  root: 'src/app/shell',
  routesDir: 'src/pages',
  ssg: { resume: true },
});

Both are opt-in: a plain weave build is unchanged, and a SPA-only app ships none of this. Anything that cannot resume client-renders instead, and says so at build time with the binding, the file and the cause. See Static generation & resume.

Scaffolded apps already include the CLI, with the scripts wired up:

npm create weave@latest my-app

📚 Guides + full API reference: Tooling guide · Config reference

License

MIT