qip-router
v0.3.0
Published
Dependency-free QIP development router for Node.js
Readme
qip-router
qip-router serves a QIP content directory with Node.js. It reads content,
recipes, component assets, and custom-element modules directly from the
filesystem, and runs QIP components with Node's WebAssembly runtime.
Documentation: https://qip.dev/docs/router
npx qip-router dev ./siteThe package has no runtime dependencies. It requires Node.js 22 or newer.
Commands
qip-router dev ./site
qip-router get ./site /docs/router
qip-router head ./site /docs/router
qip-router kindred ./site /docs/router
qip-router list ./site
qip-router warc ./site -o site.warcProject directories are discovered below the content root:
site/
_recipes/
_components/
_elements/
index.mdThey can also be supplied separately:
qip-router dev ./site \
--recipes ./recipes \
--components ./components \
--elements ./elementsUse --include <path> and --exclude <path> to route only part of the
content. Both flags can be repeated, and every command accepts them. The router
routes the files under any include path, or all files when there are none, and
removes the files under any exclude path:
qip-router warc ./site --exclude blog/drafts -o site.warc
qip-router dev ./site --include blog --include about.mdEither flag also skips dot paths such as .env, unless an include path names
them. Parent pages outside the filters still supply their layouts. Details are
in the router specification.
The development server listens on 127.0.0.1:4000 by default. Existing
content files are read for each request. A browser hard refresh reloads the
route table and recipe modules, so newly added files and changed recipes take
effect without restarting the process.
JavaScript API
The executable is also an ES module:
import { createQIPRouter } from "qip-router";
const router = await createQIPRouter({ contentRoot: "./site" });
const server = await router.listen({ port: 4000 });router.fetch(request) returns a standard Fetch API Response, which lets QIP
Router mount inside Hono, Workers-style runtimes, and other Fetch-native hosts.
router.get(path) and router.head(path) resolve requests without opening a
network socket and return { status, headers, body }. router.head(path) sets
HEAD headers such as content-length, but its body is an empty Uint8Array.
router.kindred(path) lists the parent pages and direct src or eligible
<link href> dependencies supplied as Kindred Route context for one path.
router.resolve(method, path) is available when the method is
dynamic. The include and exclude options take arrays of paths and work like
the command-line flags.
router.warc() returns the transformed full-site WARC as a Uint8Array.
router.warc({ checkKindred: true }), or qip-router warc --check-kindred on
the command line, also reruns each page's WARC recipes with only its Kindred
Routes, as dev does, and rejects if any page's output differs. Pages are
checked in parallel on a pool of worker threads, one per CPU core. If one page's
WARC recipes run longer than 5 seconds (kindredPageTimeoutMs), the check stops
there and rejects, without checking the remaining pages.
app.all("/docs/*", async (c) => {
const url = new URL(c.req.url);
url.pathname = url.pathname.slice("/docs".length) || "/";
return router.fetch(new Request(url, c.req.raw));
});Current boundary
The Node router implements content recipes, raw Markdown routes, component and element assets, Kindred Route WARC transforms, and lazy full-site-derived routes. Its page and full-site WARC output are tested byte-for-byte against the Go router.
Recipe execution is synchronous WebAssembly. A component that does not return can therefore block the Node process. Use the Go router when execution timeouts are required; a future Node isolation layer can use worker threads without adding a package dependency.
