htmx-router 1.0.0-alpha.6 → 1.0.0-pre2

package/package.json

@@ -1,19 +1,17 @@
 {
 	"name": "htmx-router",
-	"version": "1.0.0-alpha.6",
-	"description": "A simple SSR framework with dynamic+client islands",
+	"version": "1.0.0-pre2",
+	"description": "A lightweight SSR framework with server+client islands",
 	"keywords": [
-		"htmx",
-		"router",
-		""
+		"htmx", "router", "client islands", "ssr", "vite"
 	],
 	"main": "./index.js",
 	"type": "module",
 	"scripts": {
-		"build": "tsc && tsc-alias"
+		"build": "tsc"
 	},
 	"bin": {
-		"htmx-router": "./cli/index.js"
+		"htmx-router": "cli/index.js"
 	},
 	"repository": {
 		"type": "git",
@@ -31,8 +29,8 @@
 	},
 	"devDependencies": {
 		"@types/node": "^20.4.5",
+		"chalk": "^5.4.1",
 		"ts-node": "^10.9.1",
-		"tsc-alias": "^1.8.10",
 		"typescript": "^5.1.6"
 	}
 }

package/readme.md

@@ -1,5 +1,22 @@
-# htmx Router
+# HTMX Router
 
-A simple file based router with support for: dynamic + client islands; route-less endpoints; client/server bundle spitting, and built in CSS sheet generation.
+A lightweight file based router built on vite+htmx for SSR generation of full pages and html partials
 
-> Apologies the docs have not yet been updated for this version, please wait for the final release for actual docs.
+Features:
+
+  - BYO jsx templating
+  - File base routing
+  - Typesafe url path parameters
+  - Dynamic route fallthrough
+  - Server + Client Islands
+  - Route-less points
+  - CSS sheet generation
+  - [html](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta), [opengraph](https://ogp.me/), and [json+ld](https://json-ld.org/) metadata generation
+  - Bundle splitting for filtering out server code from the client
+  - Server-Side EventSource creation for SSE event dispatch
+
+## Documentation
+See https://htmx-router.ajanibilby.com/
+
+## API
+See https://htmx-router.ajanibilby.com/api

package/router.d.ts

@@ -1,36 +1,27 @@
-import { Parameterized, ParameterShaper } from './util/parameters.js';
+import type { GenericContext } from "./internal/router.js";
+import { Parameterized, ParameterPrelude, ParameterShaper } from './util/parameters.js';
 import { RouteModule } from "./index.js";
 import { Cookies } from './cookies.js';
-export declare function GenerateRouteTree(modules: Record<string, unknown>): RouteTree;
-export declare class GenericContext {
-    request: Request;
-    headers: Headers;
-    cookie: Cookies;
-    params: {
-        [key: string]: string;
-    };
-    url: URL;
-    render: (res: JSX.Element) => Response;
-    constructor(request: GenericContext["request"], url: GenericContext["url"], renderer: GenericContext["render"]);
-    shape<T extends ParameterShaper>(shape: T): RouteContext<T>;
-}
+export declare function GenerateRouteTree(props: {
+    modules: Record<string, unknown>;
+    scope: string;
+}): RouteTree;
 export declare class RouteContext<T extends ParameterShaper = {}> {
-    request: Request;
-    headers: Headers;
-    cookie: Cookies;
-    params: Parameterized<T>;
-    url: URL;
+    readonly request: Request;
+    readonly headers: Headers;
+    readonly cookie: Cookies;
+    readonly params: Parameterized<T>;
+    readonly url: URL;
     render: (res: JSX.Element) => Response;
-    constructor(base: GenericContext, shape: T);
+    constructor(base: GenericContext | RouteContext, params: ParameterPrelude<T>, shape: T);
 }
 export declare class RouteTree {
-    root: boolean;
-    nested: Map<string, RouteTree>;
-    index: RouteLeaf | null;
-    slug: RouteLeaf | null;
-    wild: RouteTree | null;
-    wildCard: string;
-    constructor(root?: boolean);
+    private nested;
+    private index;
+    private slug;
+    private wild;
+    private wildCard;
+    constructor();
     ingest(path: string | string[], module: RouteModule<any>): void;
     resolve(fragments: string[], ctx: GenericContext): Promise<Response | null>;
     private _resolve;
@@ -38,14 +29,5 @@ export declare class RouteTree {
     private resolveNext;
     private resolveWild;
     private resolveSlug;
-    private resolveNative;
     private unwrap;
 }
-declare class RouteLeaf {
-    module: RouteModule<any>;
-    constructor(module: RouteModule<any>);
-    resolve(ctx: GenericContext): Promise<Response | null>;
-    error(ctx: GenericContext, e: unknown): Promise<Response>;
-    private renderWrapper;
-}
-export {};

package/router.js

@@ -1,43 +1,29 @@
 import { ServerOnlyWarning } from "./internal/util.js";
 ServerOnlyWarning("router");
+// builtin routes
 import * as endpoint from './endpoint.js';
-import * as dynamic from './dynamic.js';
+import * as dynamic from './defer.js';
 import * as mount from './internal/mount.js';
 import * as css from './css.js';
-import { Parameterize } from './util/parameters.js';
-import { Cookies } from './cookies.js';
-export function GenerateRouteTree(modules) {
+export function GenerateRouteTree(props) {
+    if (!props.scope.endsWith("/"))
+        props.scope += "/";
     const tree = new RouteTree();
-    for (const path in modules) {
-        const mod = modules[path];
+    for (const path in props.modules) {
+        const mod = props.modules[path];
         const tail = path.lastIndexOf(".");
-        const url = path.slice(9, tail);
+        const url = path.slice(props.scope.length, tail);
         tree.ingest(url, mod);
         if (mod.route)
             mod.route(url);
     }
+    // ingest router builtins
+    tree.ingest(endpoint.path, endpoint);
+    tree.ingest(dynamic.path, dynamic);
+    tree.ingest(mount.path, mount);
+    tree.ingest(css.path, css);
     return tree;
 }
-export class GenericContext {
-    request;
-    headers; // response headers
-    cookie;
-    params;
-    url;
-    render;
-    constructor(request, url, renderer) {
-        this.cookie = new Cookies(request.headers);
-        this.headers = new Headers();
-        this.request = request;
-        this.params = {};
-        this.url = url;
-        this.render = renderer;
-        this.headers.set("x-powered-by", "htmx-router");
-    }
-    shape(shape) {
-        return new RouteContext(this, shape);
-    }
-}
 export class RouteContext {
     request;
     headers; // response headers
@@ -45,31 +31,39 @@ export class RouteContext {
     params;
     url;
     render;
-    constructor(base, shape) {
-        this.params = Parameterize(base.params, shape);
+    constructor(base, params, shape) {
         this.cookie = base.cookie;
         this.headers = base.headers;
         this.request = base.request;
         this.render = base.render;
         this.url = base.url;
+        this.params = {};
+        for (const key in shape) {
+            if (!(key in params))
+                console.warn(`Parameter ${key} not present in route, but defined in parameters`);
+            const func = shape[key];
+            const val = func(params[key] || "");
+            // NaN moment
+            if (func === Number && typeof val === "number" && isNaN(val))
+                throw new Error("Invalid Number");
+            this.params[key] = val;
+        }
     }
 }
 export class RouteTree {
-    root;
     nested;
     // Leaf nodes
-    index; // about._index
-    // Wild card route
+    index; // _index.tsx
+    // Wild card routes
     slug; // $
     wild; // e.g. $userID
     wildCard;
-    constructor(root = true) {
-        this.root = root;
+    constructor() {
         this.nested = new Map();
+        this.index = null;
         this.wildCard = "";
-        this.slug = null;
         this.wild = null;
-        this.index = null;
+        this.slug = null;
     }
     ingest(path, module) {
         if (!Array.isArray(path))
@@ -87,7 +81,7 @@ export class RouteTree {
             // Check wildcard isn't being changed
             if (!this.wild) {
                 this.wildCard = wildCard;
-                this.wild = new RouteTree(false);
+                this.wild = new RouteTree();
             }
             else if (wildCard !== this.wildCard) {
                 throw new Error(`Redefinition of wild card ${this.wildCard} to ${wildCard}`);
@@ -98,7 +92,7 @@ export class RouteTree {
         }
         let next = this.nested.get(path[0]);
         if (!next) {
-            next = new RouteTree(false);
+            next = new RouteTree();
             this.nested.set(path[0], next);
         }
         path.splice(0, 1);
@@ -115,8 +109,7 @@ export class RouteTree {
         }
     }
     async _resolve(fragments, ctx) {
-        let res = await this.resolveNative(fragments, ctx)
-            || await this.resolveIndex(fragments, ctx)
+        let res = await this.resolveIndex(fragments, ctx)
             || await this.resolveNext(fragments, ctx)
             || await this.resolveWild(fragments, ctx)
             || await this.resolveSlug(fragments, ctx);
@@ -161,15 +154,6 @@ export class RouteTree {
             : null;
         return res;
     }
-    async resolveNative(fragments, ctx) {
-        if (!this.root)
-            return null;
-        if (fragments.length < 2)
-            return null;
-        if (fragments[0] != "_")
-            return null;
-        return await ResolveNatively(fragments, ctx);
-    }
     async unwrap(ctx, res) {
         if (!this.slug)
             throw res;
@@ -220,12 +204,3 @@ class RouteLeaf {
         return null;
     }
 }
-async function ResolveNatively(fragments, ctx) {
-    switch (fragments[1]) {
-        case "dynamic": return dynamic._resolve(fragments, ctx);
-        case "endpoint": return endpoint._resolve(fragments, ctx);
-        case "mount": return mount._resolve(fragments);
-        case "style": return css._resolve(fragments);
-    }
-    return null;
-}

package/shell.d.ts

@@ -1,5 +1,5 @@
 export type ShellOptions<D = {}> = D & MetaDescriptor;
-export declare function ApplyMetaDescriptorDefaults(options: ShellOptions, defaults: Readonly<Partial<ShellOptions>>): void;
+export declare function ApplyMetaDefaults(options: ShellOptions, defaults: Readonly<Partial<ShellOptions>>): void;
 export type InferShellOptions<F> = F extends (jsx: any, options: infer U) => any ? U : never;
 export type MetaDescriptor = {
     title?: string;

package/shell.js

@@ -1,6 +1,6 @@
 import { ServerOnlyWarning } from "./internal/util.js";
 ServerOnlyWarning("shell");
-export function ApplyMetaDescriptorDefaults(options, defaults) {
+export function ApplyMetaDefaults(options, defaults) {
     if (defaults.title && !options.title)
         options.title = defaults.title;
     if (defaults.description && !options.description)
@@ -26,14 +26,22 @@ export function RenderMetaDescriptor(options) {
         for (const json of options.jsonLD) {
             out += `<script type="application/ld+json">${JSON.stringify(json)}</script>\n`;
         }
-    // Auto apply og:title + og:description if not present
-    if (options.title && !options.og?.title)
-        out += `<meta property="og:title" content="${EscapeHTML(options.title)}">\n`;
-    if (options.description && !options.og?.description)
-        out += `<meta property="og:description" content="${EscapeHTML(options.description)}">\n`;
     // Apply open graphs
-    if (options.og)
+    if (options.og) {
+        // Infer from meta if not present
+        if (!options.og.title)
+            options.og.title = options.title;
+        if (!options.og.description)
+            options.og.title = options.description;
         out += RenderOpenGraph(options.og);
+    }
+    else {
+        // Auto apply og:title + og:description if og not present
+        if (options.title)
+            out += `<meta property="og:title" content="${EscapeHTML(options.title)}">\n`;
+        if (options.description)
+            out += `<meta property="og:description" content="${EscapeHTML(options.description)}">\n`;
+    }
     return out;
 }
 function RenderOpenGraph(og) {

package/util/parameters.d.ts

@@ -1,7 +1,10 @@
+export type ParameterShaper = Record<string, (val: string) => any>;
+export type ParameterPrelude<T extends ParameterShaper> = {
+    [K in keyof T]: string;
+};
 export type Parameterized<T extends ParameterShaper> = {
     [K in keyof T]: ReturnType<T[K]>;
 };
-export type ParameterShaper = Record<string, (val: string) => any>;
-export declare function Parameterize<T extends ParameterShaper>(params: {
-    [key: string]: string;
-}, shape: T): Parameterized<T>;
+export type Parameterizer<T extends ParameterShaper> = {
+    [K in keyof T]: (val: ReturnType<T[K]>) => string;
+};

package/util/parameters.js

@@ -1,14 +1 @@
-export function Parameterize(params, shape) {
-    const out = {};
-    for (const key in shape) {
-        if (!(key in params))
-            console.warn(`Parameter ${key} not present in route, but defined in parameters`);
-        const func = shape[key];
-        const val = func(params[key] || "");
-        // NaN moment
-        if (func === Number && typeof val === "number" && isNaN(val))
-            throw new Error("Invalid Number");
-        out[key] = val;
-    }
-    return out;
-}
+export {};

package/dynamic.d.ts

@@ -1,5 +0,0 @@
-import type { GenericContext } from "./router.js";
-type Loader<T> = (ctx: GenericContext, params: T) => Promise<JSX.Element | Response>;
-export declare function DynamicReference<T extends Record<string, string>>(loader: Loader<T>, params?: T): string;
-export declare function _resolve(fragments: string[], ctx: GenericContext): Promise<Response | null>;
-export {};

package/dynamic.js

@@ -1,42 +0,0 @@
-import { ServerOnlyWarning } from "./internal/util.js";
-ServerOnlyWarning("dynamic-ref");
-import { QuickHash } from "./internal/util.js";
-const registry = new Map();
-const index = new Map();
-function Register(load) {
-    const existing = index.get(load);
-    if (existing)
-        return existing;
-    const hash = QuickHash(String(load));
-    const name = `${encodeURIComponent(load.name)}-${hash}`;
-    registry.set(name, load);
-    const url = `/_/dynamic/${name}`;
-    index.set(load, url);
-    return url;
-}
-export function DynamicReference(loader, params) {
-    let url = Register(loader);
-    if (params) {
-        const query = new URLSearchParams();
-        if (params)
-            for (const key in params)
-                query.set(key, params[key]);
-        url += "?" + query.toString();
-    }
-    return url;
-}
-export async function _resolve(fragments, ctx) {
-    if (!fragments[2])
-        return null;
-    const endpoint = registry.get(fragments[2]);
-    if (!endpoint)
-        return null;
-    const props = {};
-    for (const [key, value] of ctx.url.searchParams)
-        props[key] = value;
-    ctx.headers.set("X-Partial", "true");
-    const res = await endpoint(ctx, props);
-    if (res instanceof Response)
-        return res;
-    return ctx.render(res);
-}

package/example/eventdim-react/package.json

@@ -1,67 +0,0 @@
-{
-	"name": "eventdim-react",
-	"private": "true",
-	"version": "1.0.0",
-	"main": "index.js",
-	"type": "module",
-	"scripts": {
-		"prepare": "npx htmx-router && prisma generate && prisma migrate deploy",
-		"docker": "docker compose up -d",
-		"dev": "node ./server.js",
-		"build": "run-s build:*",
-		"build:router": "npx htmx-router",
-		"build:prisma": "npx prisma generate",
-		"build:client": "vite build",
-		"build:server": "vite build --ssr app/entry.server.ts --outDir dist/server",
-		"validate": "run-s validate:*",
-		"validate:typecheck": "tsc --noEmit",
-		"validate:lint": "eslint --ignore-path .gitignore --cache --cache-location ./node_modules/.cache/eslint .",
-		"preview": "cross-env NODE_ENV=production node ./server.js"
-	},
-	"keywords": [],
-	"author": "",
-	"license": "ISC",
-	"description": "",
-	"dependencies": {
-		"@fortawesome/free-brands-svg-icons": "^6.7.2",
-		"@fortawesome/free-solid-svg-icons": "^6.7.2",
-		"@fortawesome/react-fontawesome": "^0.2.2",
-		"@prisma/client": "^6.1.0",
-		"bcryptjs": "^2.4.3",
-		"cbor2": "^1.8.0",
-		"cross-env": "^7.0.3",
-		"dotenv": "^16.4.7",
-		"express": "^4.21.2",
-		"htmx-router": "^1.0.0-alpha.5",
-		"morgan": "^1.10.0",
-		"react": "^19.0.0",
-		"react-dom": "^19.0.0",
-		"tiny-invariant": "^1.3.3",
-		"zxcvbn": "^4.4.2"
-	},
-	"devDependencies": {
-		"@types/bcryptjs": "^2.4.6",
-		"@types/express": "^4.17.21",
-		"@types/nodemailer": "^6.4.15",
-		"@types/react": "^18.2.20",
-		"@types/react-dom": "^18.2.7",
-		"@types/zxcvbn": "^4.4.4",
-		"@typescript-eslint/eslint-plugin": "^6.7.4",
-		"@typescript-eslint/parser": "^6.7.4",
-		"eslint": "^8.38.0",
-		"eslint-import-resolver-typescript": "^3.6.1",
-		"eslint-plugin-import": "^2.28.1",
-		"eslint-plugin-jsx-a11y": "^6.7.1",
-		"eslint-plugin-react": "^7.33.2",
-		"eslint-plugin-react-hooks": "^4.6.0",
-		"npm-run-all": "^4.1.5",
-		"prisma": "^6.1.0",
-		"typed-htmx": "^0.3.1",
-		"typescript": "^5.5.4",
-		"vite-tsconfig-paths": "^5.1.3",
-		"vite": "^6.0.1"
-	},
-	"engines": {
-		"node": ">=20.0.0"
-	}
-}

package/example/eventdim-react/server.js

@@ -1,90 +0,0 @@
-/// <reference types="node" />
-/* eslint-disable */
-import 'dotenv/config'
-import * as path from "path";
-import { createRequestHandler } from 'htmx-router';
-import { renderToString } from 'react-dom/server';
-import express from 'express';
-import morgan from "morgan";
-
-const port = process.env.PORT || 3000;
-const app = express();
-
-const viteDevServer =
-	process.env.NODE_ENV === "production"
-		? null
-		: await import("vite").then((vite) =>
-				vite.createServer({
-					server: { middlewareMode: true },
-					appType: 'custom'
-				})
-			);
-
-app.use(
-	viteDevServer
-		? viteDevServer.middlewares
-		: express.static("./dist/client")
-);
-
-// logging
-app.use(morgan("tiny"));
-
-const build = viteDevServer
-	? () => viteDevServer.ssrLoadModule('./app/entry.server.ts')
-	: await import('./dist/server/entry.server.js');
-
-app.use('*', createRequestHandler.http({
-	build, viteDevServer,
-	render: (res) => {
-		const headers = new Headers();
-		headers.set("Content-Type", "text/html; charset=UTF-8");
-		headers.set("Cache-Control", "no-cache");
-
-		const stream = renderToString(res);
-		return new Response(stream, { headers });
-	}
-}));
-
-// Start http server
-app.listen(port, () => {
-	console.log(`Server started at http://localhost:${port}`)
-})
-
-
- // Reload pages on file change
-if (viteDevServer) {
-	const focus = path.resolve("./app");
-	viteDevServer.watcher.on('change', (file) => {
-		if (!file.startsWith(focus)) return;
-		console.log(`File changed: ${path.relative("./app", file)}`);
-
-		console.log('Triggering full page reload');
-		viteDevServer.ws.send({ type: 'full-reload' });
-	});
-}
-
-const shutdown = () => {
-	console.log("Shutting down server...");
-
-	// Close the server gracefully
-	server.close((err) => {
-		if (err) {
-			console.error("Error during server shutdown:", err);
-			process.exit(1);
-		}
-		console.log("Server shut down gracefully.");
-		process.exit(0);
-	});
-};
-
-process.on('SIGTERM', shutdown);
-process.on('SIGHUP', shutdown);
-
-
-process .on('unhandledRejection', (reason, p) => {
-	console.error(reason, 'Unhandled Rejection at Promise', p);
-})
-.on('uncaughtException', err => {
-	console.error(err, 'Uncaught Exception thrown');
-	process.exit(1);
-});

package/example/island-react/global.d.ts

@@ -1,8 +0,0 @@
-import { ReactNode } from 'react';
-
-declare global {
-	namespace JSX {
-		type Element = ReactNode;
-		interface HTMLAttributes extends HtmxAttributes {}
-	}
-}

package/example/island-react/package.json

@@ -1,38 +0,0 @@
-{
-	"type": "module",
-	"scripts": {
-		"prepare": "npx htmx-router",
-		"dev": "node ./server.js",
-		"build": "run-s build:*",
-		"build:router": "npx htmx-router",
-		"build:client": "vite build",
-		"build:server": "vite build --ssr app/entry.server.ts --outDir dist/server",
-		"preview": "cross-env NODE_ENV=production node ./server.js",
-		"validate": "npx tsc -noEmit"
-	},
-	"license": "MIT",
-	"dependencies": {
-		"cross-env": "^7.0.3",
-		"dotenv": "^16.3.1",
-		"express": "^4.21.1",
-		"morgan": "^1.10.0",
-		"npm-run-all": "^4.1.5",
-		"htmx-router": "^1.0.0-alpha.1",
-		"react": "^19.0.0",
-		"react-dom": "^19.0.0",
-		"serve-static": "^1.16.2",
-		"tsconfig-paths": "^4.2.0"
-	},
-	"devDependencies": {
-		"@types/express": "^5.0.0",
-		"@types/node": "^20.4.5",
-		"@types/react-dom": "^19.0.2",
-		"@types/react": "^19.0.1",
-		"@types/serve-static": "^1.15.7",
-		"ts-node": "^10.9.1",
-		"typed-htmx": "^0.3.1",
-		"typescript": "^5.1.6",
-		"vite-tsconfig-paths": "^5.1.3",
-		"vite": "^6.0.1"
-	}
-}