htmx-router 1.0.0-alpha.5 → 1.0.0-pre1

package/example/eventdim-react/package.json

@@ -0,0 +1,67 @@
+{
+	"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

@@ -0,0 +1,90 @@
+/// <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

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

package/example/island-react/package.json

@@ -0,0 +1,38 @@
+{
+	"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"
+	}
+}

package/example/island-react/server.js

@@ -0,0 +1,58 @@
+import { createRequestHandler } from 'htmx-router';
+import { renderToString } from 'react-dom/server';
+import express from 'express';
+import morgan from "morgan";
+
+const port = process.env.PORT || 5173;
+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");
+
+		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)
+	viteDevServer.watcher.on('change', (file) => {
+	console.log(`File changed: ${file}`);
+
+	console.log('Triggering full page reload');
+	viteDevServer.ws.send({ type: 'full-reload' });
+});

package/global.d.ts

@@ -0,0 +1,7 @@
+declare namespace JSX {
+	interface Element {}
+	interface IntrinsicElements {
+		[elementName: string]: any;
+	}
+	interface Fragment {}
+}

package/package.json

@@ -1,15 +1,17 @@
 {
 	"name": "htmx-router",
-	"version": "1.0.0-alpha.5",
-	"description": "A simple SSR framework with dynamic+client islands",
-	"keywords": ["htmx", "router", ""],
-	"main": "./bin/index.js",
+	"version": "1.0.0-pre1",
+	"description": "A lightweight SSR framework with server+client islands",
+	"keywords": [
+		"htmx", "router", "client islands", "ssr", "vite"
+	],
+	"main": "./index.js",
 	"type": "module",
 	"scripts": {
-		"build": "tsc && tsc-alias"
+		"build": "tsc"
 	},
 	"bin": {
-		"htmx-router": "bin/cli/index.js"
+		"htmx-router": "cli/index.js"
 	},
 	"repository": {
 		"type": "git",
@@ -23,12 +25,12 @@
 	"homepage": "https://github.com/AjaniBilby/htmx-router#readme",
 	"dependencies": {
 		"es-module-lexer": "^1.5.4",
-		"vite": "^6.0.1"
+		"vite": "^6.0.6"
 	},
 	"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,217 +1,22 @@
-# htmx Router
+# HTMX Router
 
-A simple file based router with support for dynamic + client islands, route-less endpoints, and built in CSS sheet generation.
+A lightweight file based router built on vite+htmx for SSR generation of full pages and html partials
 
-- [htmx Router](#htmx-router)
-	- [Setup](#setup)
-	- [Routing](#routing)
-		- [Route Module](#route-module)
-		- [Nested Route Rendering](#nested-route-rendering)
-		- [JSX Rendering](#jsx-rendering)
-	- [Route Contexts](#route-contexts)
-		- [Params](#params)
-		- [Cookies](#cookies)
-		- [Headers](#headers)
-		- [Request](#request)
-		- [URL](#url)
-	- [Style Sheets](#style-sheets)
-	- [Route-less Endpoint](#route-less-endpoint)
-	- [Islands](#islands)
-		- [Dynamic](#dynamic)
-		- [Client](#client)
+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
 
-## Setup
+## Documentation
+See https://htmx-router.ajanibilby.com/
 
-Create a `htmx-router.json` in the root of your project defining where you want your router file to be placed, and where your routes are.
-You can also define where you want to create your client component bindings, and for what target framework.
-```json
-{
-	"router": {
-		"folder": "./source/routes",
-		"output": "./source/router.tsx"
-	},
-	"client": {
-		"adapter": "react",
-		"source": "./source/client.tsx"
-	}
-}
-```
-
-Once you have done this, run `npx htmx-router` to generate the artifacts to start development.
-We recommand you copy the setup from `examples/react` for your `server.js`, `entry.server.ts`, and `entry.client.ts`.
-
-Don't forget that in all rendered routes you must include the `<RouterHeader/>` component in your head for hydration and `StyleClass`s to apply affectively.
-
-
-## Routing
-
-Routing applies in a depth first order, where it will match in order:
-  1. The `_index`
-  2. Static sub-routes
-  3. Url path-param wildcards
-  4. Catchall slug
-
-This allows for easy overriding and fallback behaviour. For instance with the routes.
-```
-/user/$id.tsx
-/user/me.tsx
-/user/$.tsx
-```
-
-It will match on the `/user/me` route if applicable, and otherwise will fallback to attempt to match on `/user/$id`, and if the wildcard route fails, it will try the generic slug route `/user/$.tsx`.
-
-If a route returns `null` the router will continue the depth first search, allowing for dynamic flow through of the routes.
-
-### Route Module
-
-A route module must define a `parameters` export, which defines how the url path params should be parsed when attempting to match the route.
-You can use any function which takes a string, and returns something as the parser. You can also simply use JS-Builtin functions for this, and there is a special case with the `Number` function so it will reject on `NaN` values.
-```js
-export const parameters = { id: Number };
-```
-
-A route can additionally define a loader, which is called on `GET` and `HEAD` requests
-```ts
-export async function loader({}: RouteContext<typeof parameters>);
-```
-
-With the `action` function being called for all other methods
-```ts
-export async function action({}: RouteContext<typeof parameters>);
-```
-
-If any value is thrown by the parameter parsing, or the render functions (`loader`/`action`) it will boil up, attempting first to call an error function is supplied in the route, and otherwise boiling up to the nearest slug route's `error` function.
-```ts
-export async function error(ctx: GenericContext, error: unknown);
-```
-
-### Nested Route Rendering
-
-The router will not do nested layouts, if that behaviour is required we recommend using the slug-shell pattern.
-Where you define a slug route, and export a `shell` function which takes the `JSX` rendered result from the sub route, and renders the upper route around it.
-
-This allows flexibility at runtime on how nested route rendering behaves, and can also allow you to ensure you are not reloading data from the db which is already loaded by a sub-route based on how you parse up data through your slug shells.
-
-We recommend you look at [Predictable Bot](https://github.com/AjaniBilby/predictable) as an example of this pattern performed simply.
-
-
-### JSX Rendering
-
-htmx-router is jsx templating agnostic for SSR, instead only requiring a definition provided when creating your request handler, allowing you to BYO JSX templating.
-```js
-// @kitajs/html
-app.use('*', createRequestHandler.http({
-	build,
-	viteDevServer,
-	render: (res) => {
-		const headers = new Headers();
-		headers.set("Content-Type", "text/html; charset=UTF-8");
-		return new Response(String(res), { headers });
-	}
-}));
-
-// React
-app.use('*', createRequestHandler.http({
-	build,
-	viteDevServer,
-	render: (res) => {
-		const headers = new Headers();
-		headers.set("Content-Type", "text/html; charset=UTF-8");
-		return new Response(renderToString(res), { headers });
-	}
-}));
-```
-
-## Route Contexts
-
-There are two kinds of route context, the `RouteContext<T>` which is the resolved route with parameterization, and the `GenericContext` which is used by error functions, and dynamic loads.
-
-### Params
-
-In the `GenericContext` this will simply be an object with string key value pairs for the parameters, and only the `RouteContext<T>` for `loader` and `action` will have the parameters pre-parsed by your `parameters` definition.
-
-### Cookies
-
-The `RouteContext` and `GenericContext`s both provide a `cookie` object, with the cookie's pre-parsed from the request headers.
-It also has a built in `set(name, value, options)` function which will add the appropriate headers to the response for the cookie changes.
-
-### Headers
-
-This is a header object useful for adding response headers when you haven't fully finished generating your response yet.
-These headers will merge with the response object created by the provided `render` function, with response headers overriding any conflicting `ctx.headers` values.
-
-### Request
-
-This is the original request object, including request headers.
-
-### URL
-
-The parsed `URL` object of the incoming request.
-
-## Style Sheets
-
-htmx-router includes a `StyleClass` object, which can be used to define CSS classes without needing a unique name.
-StyleClasses should only be defined at the top level of a file, and not created within a function, or dynamically during runtime.
-
-```ts
-const myClass = new StyleClass(`myClass`, `
-.this:hover {
-	background-color: red;
-}
-`).name;
-```
-
-## Route-less Endpoint
-
-This should be defined at the top level of your file, these endpoints can optionally be given an name which will help for debugging network requests, but they do not need to be unique.
-```ts
-const endpoint_url = new Endpoint((ctx: GenericContext) => {
-	return new Response("Hello World");
-}, "hello-world").url;
-```
-
-## Islands
-
-> Tip: Don't forget to wrap your islands in a hx-preserve to prevent losing state. And use `display: contents;` to make that wrapping div transparent for grid and other layout features.
-
-### Dynamic
-
-A dynamic component takes params which will be converted into the props of the loader function, these props may only be string key string value pairs as they are encoded the the query string to allow for browser side caching.
-
-The body of a dynamic component is the pre-rendered infill that will display while the client is loading the dynamic content.
-
-```tsx
-async function MyProfile(params: {}, ctx: GenericContext): Promise<JSX.Element> {
-	ctx.headers.set('Cache-Control', "private, max-age=120");
-	const userID = ctx.cookie.get('userID');
-	if (!userID) return <></>;
-
-	const user = await GetUser(userID);
-	if (!user) return <></>;
-
-	return <a href={`/user/${userID}`}>
-		<div safe>{user.name}</div>
-	</a>
-}
-
-export async function loader({ params }: RouteContext<typeof parameters>) {
-	return <Dynamic params={{}} loader={MyProfile}>
-		put your ssr pre-rendered skeleton here
-	</Dynamic>
-}
-```
-
-### Client
-
-Import all of the components you want to be able to use on the client side into your `client.tsx`, if you are running a dev server this file will automatically generate the clientized version, otherwise use the `npx htmx-router` command to regenerate these artifacts.
-
-Once a component has been clientized you can import it as use it like normal, however the body is now overwritten to it will render immediately on the server, and then all props will parsed to the client for it to be rendered properly in the browser.
-
-```tsx
-<Client.Counter>
-	<button>No yet hydrated...</button> {/* this will be overwritten in the browser once hydrated */}
-</Client.Counter>
-```
-
-It is very important that you ensure your `Client` component has a single child element, if there are multiple child components the browser will only mount to the last child causing artifacting.
+## API
+See https://htmx-router.ajanibilby.com/api

package/bin/cli/config.d.ts

@@ -1,10 +0,0 @@
-export declare function ReadConfig(): Promise<{
-    client?: {
-        adapter: string;
-        source: string;
-    };
-    router: {
-        folder: string;
-        output: string;
-    };
-}>;

package/bin/cli/config.js

@@ -1,4 +0,0 @@
-import { readFile } from "fs/promises";
-export async function ReadConfig() {
-    return JSON.parse(await readFile(process.argv[2] || "./htmx-config.json", "utf-8"));
-}

package/bin/cli/index.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-export {};

package/bin/cli/index.js

@@ -1,66 +0,0 @@
-#!/usr/bin/env node
-"use strict";
-import { writeFile } from "fs/promises";
-import { relative } from "path";
-import { GenerateClient } from "../client/index.js";
-import { ReadConfig } from "../cli/config.js";
-const config = await ReadConfig();
-console.info("Building router");
-const routes = relative(config.router.output, config.router.folder).replaceAll("\\", "/").slice(1);
-await writeFile(config.router.output, `/*------------------------------------------
- * Generated by htmx-router                *
- * Warn: Any changes will be overwritten   *
--------------------------------------------*/
-/* eslint-disable @typescript-eslint/no-explicit-any */
-
-import { GenericContext, RouteTree } from "htmx-router/bin/router";
-import { GetClientEntryURL } from 'htmx-router/bin/client/entry';
-import { DynamicReference } from "htmx-router/bin/util/dynamic";
-import { GetMountUrl } from 'htmx-router/bin/client/mount';
-import { GetSheetUrl } from 'htmx-router/bin/util/css';
-import { RouteModule } from "htmx-router";
-import { resolve } from "path";
-
-(globalThis as any).HTMX_ROUTER_ROOT = resolve('${config.router.folder.replaceAll("\\", "/")}');
-const modules = import.meta.glob('${routes}/**/*.{ts,tsx}', { eager: true });
-
-export const tree = new RouteTree();
-for (const path in modules) {
-	const tail = path.lastIndexOf(".");
-	const url = path.slice(${routes.length + 1}, tail);
-	tree.ingest(url, modules[path] as RouteModule<any>);
-}
-
-export function Dynamic<T extends Record<string, string>>(props: {
-	params?: T,
-	loader: (ctx: GenericContext, params?: T) => Promise<JSX.Element>
-	children?: JSX.Element
-}): JSX.Element {
-	return <div
-		hx-get={DynamicReference(props.loader, props.params)}
-		hx-trigger="load"
-		hx-swap="outerHTML transition:true"
-		style={{ display: "contents" }}
-	>{props.children ? props.children : ""}</div>
-}
-
-let headCache: JSX.Element | null = null;
-const isProduction = process.env.NODE_ENV === "production";
-const clientEntry = await GetClientEntryURL();
-export function Scripts() {
-	if (headCache) return headCache;
-
-	const res = <>
-		<link href={GetSheetUrl()} rel="stylesheet"></link>
-		{ isProduction ? "" : <script type="module" src="/@vite/client"></script> }
-		<script type="module" src={clientEntry}></script>
-		<script src={GetMountUrl()}></script>
-	</>;
-
-	if (isProduction) headCache = res;
-	return res;
-}`);
-if (config.client) {
-    console.info("Building client islands");
-    await GenerateClient(config.client, true);
-}

package/bin/client/entry.d.ts

@@ -1 +0,0 @@
-export declare function GetClientEntryURL(): Promise<any>;

package/bin/client/entry.js

@@ -1,12 +0,0 @@
-import { readFile } from "fs/promises";
-export async function GetClientEntryURL() {
-    if (process.env.NODE_ENV !== "production")
-        return "/app/entry.client.ts";
-    const config = JSON.parse(await readFile("./dist/client/.vite/manifest.json", "utf8"));
-    for (const key in config) {
-        const def = config[key];
-        if (!def.isEntry)
-            continue;
-        return def.file;
-    }
-}

package/bin/client/index.d.ts

@@ -1,7 +0,0 @@
-/**
- * Builds the SSR and client side mounter for client components
- */
-export declare function GenerateClient(config: {
-    adapter: string;
-    source: string;
-}, force?: boolean): Promise<void>;