QueryWeave
A framework-independent, type-safe URL state engine with packages for the browser, server,
Node.js, Vue, Vue Router, and Nuxt.
Status
[!WARNING]
Experimental, pre-1.0, and not production ready. The public API is provisional and may change
between minor versions. Every breaking change is recorded in an ADR and a changeset.
The engine is implemented, tested, and validated as published archives — parameters, codecs,
models, decode results, canonical encoding, runtime transitions, and integrations for the browser,
server, Node.js, Standard Schema, Vue, Vue Router, and Nuxt.
A beta is on npm. Until a stable version exists, latest follows the newest prerelease, so
pnpm add @queryweave/core installs it. The support matrix and stability
policy say what is tested and what a version
number promises; upgrading lists every
breaking change with its migration.
A first model
import { createQueryRuntime, defineQueryModel, param } from "@queryweave/core";
const productFilters = defineQueryModel({
search: param.text().optional(),
page: param.integer({ min: 1 }).default(1),
archived: param.boolean().default(false),
sort: param.choice(["name", "created_at", "price"]).default("created_at"),
tags: param.list(param.text()).default([]),
});
const runtime = createQueryRuntime({ model: productFilters, adapter });
runtime.read().values.page; // 1
await runtime.update({ search: "vue", page: 1 });
await runtime.update({ page: 2 }, { navigation: "replace" });
await runtime.transaction((draft) => {
draft.search = "vue";
draft.page = 1;
});
In Vue, the same model gains reactivity and nothing else:
const filters = useQueryModel(productFilters);
filters.values.page; // readonly reactive state
await filters.update({ page: 2 }); // explicit operation
const search = filters.field("search", { navigation: "replace" }); // v-model target
There is no hook per key, no tuple setter, and no direct mutation as the primary API.
Why QueryWeave
URL state shows up in the browser, on the server, in tests, and in shared links. Most codebases
describe it more than once — a client parser, a server parser, a serializer, defaults repeated in
each — and those copies drift.
QueryWeave defines query state once in a model and syncs it through adapters:
Query string
↓
Decode
↓
Validate
↓
Typed state
↓
Update
↓
Canonical encoding
↓
Adapter
Vue and Nuxt are the first frontend integrations, but neither shapes the core.
Packages
| Package | Responsibility |
|---|
@queryweave/core | Models, codecs, decode/encode, and runtime contracts |
@queryweave/browser | Browser History API adapter |
@queryweave/server | Web-standard server helpers |
@queryweave/node | Node.js request integration |
@queryweave/standard-schema | Standard Schema interoperability |
@queryweave/testing | Memory adapter and test utilities |
@queryweave/vue | Vue bindings for query models |
@queryweave/vue-router | Vue Router adapter |
@queryweave/nuxt | Nuxt module and per-request runtime |
Bundle sizes
These figures are the total emitted JavaScript owned by each package. They exclude dependencies,
peer dependencies, declarations, and source maps. Each emitted .js file is minified and
compressed separately. Downstream tree-shaking can produce a smaller application cost.
Run pnpm bundle:size to rebuild the packages and update these generated tables.
pnpm bundle:size:check also enforces the minified-gzip budgets in
scripts/bundle-size-budgets.mjs.
| Package | ESM | ESM gzip | minified | min+gzip | min+Brotli |
|---|
@queryweave/core | 46.77 kB | 11.69 kB | 21.89 kB | 7.39 kB | 6.67 kB |
@queryweave/testing | 1.76 kB | 742 B | 780 B | 491 B | 433 B |
@queryweave/browser | 2.71 kB | 1.11 kB | 1.13 kB | 564 B | 472 B |
@queryweave/server | 3.05 kB | 1.22 kB | 940 B | 469 B | 409 B |
@queryweave/node | 3.77 kB | 1.45 kB | 1.32 kB | 691 B | 608 B |
@queryweave/standard-schema | 1.18 kB | 537 B | 558 B | 341 B | 299 B |
@queryweave/vue | 4.40 kB | 1.64 kB | 1.85 kB | 915 B | 829 B |
@queryweave/vue-router | 3.25 kB | 1.36 kB | 1.32 kB | 699 B | 616 B |
@queryweave/nuxt | 2.87 kB | 1.60 kB | 1.25 kB | 911 B | 781 B |
Representative consumer builds bundle actual public imports with esbuild. Framework dependencies
remain external so the figures show QueryWeave's contribution.
| Consumer scenario | minified | gzip | Brotli |
|---|
| Query string parser | 724 B | 466 B | 390 B |
| Single text model (named) | 9.60 kB | 3.24 kB | 2.94 kB |
Single text model (param) | 16.61 kB | 5.37 kB | 4.83 kB |
| Typical core runtime | 16.81 kB | 5.69 kB | 5.15 kB |
| Browser runtime | 16.19 kB | 5.67 kB | 5.11 kB |
| Web server parsing | 10.49 kB | 3.51 kB | 3.17 kB |
| Node request parsing | 11.50 kB | 3.91 kB | 3.54 kB |
| Vue binding | 16.47 kB | 5.73 kB | 5.23 kB |
| Vue + Vue Router | 17.77 kB | 6.19 kB | 5.58 kB |
| Nuxt runtime | 18.27 kB | 6.39 kB | 5.76 kB |
Documentation
The documentation site lives in apps/docs and is built with Astro and Starlight.
Run it with pnpm docs:dev.
Development
Use Node.js 22.13 or newer — 24 is what CI's full gate runs on — and pnpm 11.17.0. The published
packages support Node 22.12 and newer.
pnpm install --frozen-lockfile
pnpm check
Common commands:
pnpm dev
pnpm build
pnpm typecheck
pnpm lint
pnpm format
pnpm test # every Vitest project, including browser and type tests
pnpm test:browser # Vitest Browser Mode with Playwright and Chromium
pnpm test:types # type-level assertions only
pnpm test:coverage # every project, with coverage thresholds
pnpm test:e2e # Playwright against the browser playground
pnpm boundary:check # sources, manifests, and the dependency graph
pnpm artifacts:check # built output, archives, and declaration resolution
pnpm bundle:size # rebuild packages and update the bundle-size table
pnpm consumers:check # install packed archives into clean consumer projects
pnpm check:release # the full gate plus consumer fixtures
pnpm docs:dev
Real-browser tests run in Chromium, Firefox, and WebKit; install them once:
pnpm exec playwright install chromium firefox webkit
See ARCHITECTURE.md for boundaries,
ROADMAP.md for planned phases, and CONTRIBUTING.md before
opening a change.
License
MIT
