npm - kempo-server - Versions diffs - 1.10.5 → 1.10.7 - Mend

kempo-server 1.10.5 → 1.10.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/README.md CHANGED Viewed

@@ -366,6 +366,12 @@ npm run tests:gui     # Start the GUI test runner
 For advanced usage (filters, flags, GUI options), see:
 https://github.com/dustinpoissant/kempo-testing-framework
+## Single-Page Applications
+Kempo Server makes it easy to serve SPAs by using `customRoutes` to redirect all HTML requests to your shell page while still serving individual page fragments from a `pages/` directory.
+See **[SPA.md](./SPA.md)** for a full walkthrough.
 ## Documentation
 - **[Getting Started](./docs/getting-started.html)** - Installation and basic usage

package/SPA.md ADDED Viewed

@@ -0,0 +1,153 @@
+# Single-Page Applications
+Kempo Server supports single-page applications (SPAs) with no framework required. The approach uses `customRoutes` to redirect every HTML URL to one shell page, while individual page content lives as HTML fragments in a `pages/` directory. Client-side JavaScript handles navigation using the History API.
+## How It Works
+1. All top-level HTML requests (e.g. `/about.html`) are redirected to `app.html` via `customRoutes`.
+2. `app.html` is the shell — it contains the `<nav>`, a `<main>` content area, and loads `spa.js`.
+3. `spa.js` reads the current URL, fetches the matching fragment from `/pages/`, and injects it into `<main>`.
+4. Click events on `<a>` tags are intercepted to update the URL with `history.pushState` and load content without a full page reload.
+5. The `popstate` event handles browser back/forward navigation.
+Requests to `/pages/*.html` are **not** redirected, so the fragments are still served directly by the server.
+## File Structure
+```
+spa/
+├─ .config.json       ← server config (routes + caching)
+├─ app.html           ← shell page (loaded for every route)
+├─ spa.js             ← client-side routing logic
+└─ pages/
+   ├─ index.html      ← home page fragment
+   ├─ page1.html
+   ├─ about.html
+   ├─ contact.html
+   └─ settings.html
+```
+## Configuration
+Create a `.config.json` in your SPA root:
+```json
+{
+  "customRoutes": {
+    "/kempo.css": "../node_modules/kempo-css/dist/kempo.min.css",
+    "/*.html": "./app.html",
+    "/": "./app.html"
+  },
+  "middleware": {
+    "security": {
+      "enabled": true,
+      "headers": {
+        "Cache-Control": "public, max-age=3600"
+      }
+    }
+  }
+}
+```
+- `"/*.html": "./app.html"` — the `*` wildcard matches a single path segment, so it catches `/about.html` but not `/pages/about.html`.
+- `"/": "./app.html"` — handles requests to the root.
+- The `Cache-Control` header tells browsers to cache responses for 1 hour.
+## Shell Page (`app.html`)
+The shell page is a minimal HTML document. Navigation links use absolute paths so they work regardless of the current URL. The `<main>` element is where page content gets injected.
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>My SPA</title>
+  <link rel="stylesheet" href="/kempo.css" />
+</head>
+<body>
+  <nav>
+    <a href="/">Home</a>
+    <a href="/about.html">About</a>
+    <a href="/contact.html">Contact</a>
+  </nav>
+  <main id="main"></main>
+  <script src="/spa.js"></script>
+</body>
+</html>
+```
+## Client-Side Router (`spa.js`)
+```javascript
+const main = document.getElementById("main");
+const loadPage = path => {
+  const page = (path === "/" || path === "/index.html")
+    ? "/pages/index.html"
+    : `/pages${path}`;
+  fetch(page)
+    .then(r => {
+      if(!r.ok) throw new Error(r.status);
+      return r.text();
+    })
+    .then(html => {
+      main.innerHTML = html;
+    })
+    .catch(() => {
+      main.innerHTML = "<h1>Page Not Found</h1>";
+    });
+};
+document.addEventListener("click", e => {
+  const a = e.target.closest("a");
+  if(!a || a.origin !== location.origin) return;
+  e.preventDefault();
+  history.pushState(null, "", a.href);
+  loadPage(a.pathname);
+});
+window.addEventListener("popstate", () => {
+  loadPage(location.pathname);
+});
+loadPage(location.pathname);
+```
+### How it works
+- `loadPage` maps the URL pathname to a fragment file under `/pages/` and fetches it. The root path `/` maps to `/pages/index.html`.
+- The `click` listener intercepts same-origin link clicks, prevents the default navigation, pushes the new URL into the browser history, and loads the content.
+- The `popstate` listener handles back/forward button presses.
+- On initial load, `loadPage(location.pathname)` renders the correct content for any URL — including direct navigation and browser refreshes.
+## Page Fragments
+Each file inside `pages/` is a plain HTML fragment — just the content, no `<html>` or `<body>` wrapper needed:
+```html
+<!-- pages/about.html -->
+<h1>About</h1>
+<p>This is an example single-page application powered by Kempo-Server.</p>
+```
+## Running the SPA
+Add a script to your `package.json`:
+```json
+{
+  "scripts": {
+    "spa": "kempo-server --root ./spa"
+  }
+}
+```
+Then run:
+```bash
+npm run spa
+```
+The server starts on `http://localhost:3000` by default. All `.html` URLs load `app.html` and client-side routing takes over from there.

package/llm.txt ADDED Viewed

@@ -0,0 +1,140 @@
+# kempo-server
+Zero-dependency, file-based routing Node.js HTTP server.
+## Install & Run
+```
+npm install kempo-server
+npx kempo-server -r ./my-root -p 3000
+```
+Flags: `--root`/`-r` (default `./`), `--port`/`-p` (default `3000`), `--logging`/`-l` (0-4 or silent/minimal/verbose/debug, default 2), `--config`/`-c` path to config file (default `.config.json`).
+## File-Based Routing
+Files inside the root directory map directly to URL paths.
+| File | URL |
+|------|-----|
+| `index.html` | `/` |
+| `about.html` | `/about` or `/about.html` |
+| `api/GET.js` | `GET /api` |
+| `api/POST.js` | `POST /api` |
+| `users/[id]/GET.js` | `GET /users/:id` |
+Route files checked in order for a directory request: `METHOD.js`, `METHOD.html`, `index.js`, `index.html`.
+Allowed route file names: `GET.js POST.js PUT.js DELETE.js HEAD.js OPTIONS.js PATCH.js CONNECT.js TRACE.js index.js`
+## Route Files
+A route file exports a default async function:
+```js
+export default async (req, res) => {
+  res.json({ id: req.params.id, search: req.query.q });
+};
+```
+## Request Object
+| Property/Method | Description |
+|-----------------|-------------|
+| `req.params` | Dynamic path params from `[param]` segments |
+| `req.query` | Parsed query string as plain object |
+| `req.path` | URL path string |
+| `req.cookies` | Parsed cookies as plain object |
+| `req.body()` | Promise→string of request body |
+| `req.json()` | Promise→parsed JSON body |
+| `req.text()` | Alias for `body()` |
+| `req.buffer()` | Promise→Buffer of request body |
+| `req.get(name)` | Get request header (case-insensitive) |
+| `req.is(type)` | Check Content-Type (e.g. `'json'`) |
+## Response Object
+| Method | Description |
+|--------|-------------|
+| `res.status(code)` | Set status code, chainable |
+| `res.set(field, value)` | Set header(s), chainable; accepts object |
+| `res.get(field)` | Get response header |
+| `res.type(t)` | Set Content-Type; shortcuts: html/json/xml/text/css/js |
+| `res.json(obj)` | Send JSON response |
+| `res.send(data)` | Auto-detect: Buffer/object→json, string→text |
+| `res.html(str)` | Send HTML response |
+| `res.text(str)` | Send plain text response |
+| `res.redirect(url, code=302)` | Redirect |
+| `res.cookie(name, val, opts)` | Set cookie; opts: maxAge, domain, path, secure, httpOnly, sameSite |
+| `res.clearCookie(name, opts)` | Clear cookie |
+## Configuration (.config.json)
+```json
+{
+  "allowedMimes": { ".ext": { "mime": "type/subtype", "encoding": "utf8" } },
+  "disallowedRegex": ["pattern"],
+  "customRoutes": { "/old": "/new", "/spa/*": "/app.html" },
+  "routeFiles": ["GET.js", "index.js"],
+  "noRescanPaths": ["pattern"],
+  "maxRescanAttempts": 3,
+  "middleware": {
+    "cors": { "enabled": false, "origin": "*", "methods": "GET,POST", "headers": "*" },
+    "compression": { "enabled": false, "threshold": 1024 },
+    "rateLimit": { "enabled": false, "windowMs": 60000, "max": 100 },
+    "security": { "enabled": true, "headers": { "X-Frame-Options": "DENY" } },
+    "logging": { "enabled": true },
+    "custom": ["/middleware/auth.js"]
+  },
+  "cache": {
+    "enabled": false,
+    "maxSize": 500,
+    "maxMemoryMB": 256,
+    "ttlMs": 300000,
+    "watchFiles": true
+  }
+}
+```
+`customRoutes` values: exact path string (redirect) or `{ "file": "/path.js", "params": {} }` (custom handler file). `*` matches one path segment; `**` matches multiple.
+## Custom Middleware
+Middleware files export a default factory:
+```js
+export default config => async (req, res, next) => {
+  // req/res are the enhanced wrappers
+  await next();
+};
+```
+## Dynamic Routes
+Use `[param]` in directory names:
+```
+users/[id]/GET.js     → GET /users/123      (req.params.id === '123')
+posts/[slug]/index.js  → /posts/my-title   (req.params.slug === 'my-title')
+```
+## SPA Mode
+Use `customRoutes` to redirect all page paths to the SPA entry:
+```json
+"customRoutes": {
+  "/": "/app.html",
+  "/*.html": "/app.html"
+}
+```
+## Utility Modules
+```js
+import { getArgs } from 'kempo-server/utils/cli';
+// getArgs(mapping?) → parsed argv object
+import { ensureDir, copyDir, emptyDir } from 'kempo-server/utils/fs-utils';
+```

package/package.json CHANGED Viewed

@@ -1,11 +1,9 @@
 {
   "name": "kempo-server",
   "type": "module",
-  "version": "1.10.5",
+  "version": "1.10.7",
   "description": "A lightweight, zero-dependency, file based routing server.",
-  "main": "dist/index.js",
   "exports": {
-    ".": "./dist/index.js",
     "./utils/cli": "./dist/utils/cli.js",
     "./utils/fs-utils": "./dist/utils/fs-utils.js"
   },
@@ -15,6 +13,7 @@
   "scripts": {
     "build": "node scripts/build.js",
     "docs": "node dist/index.js -r ./docs",
+    "spa": "node dist/index.js -r ./spa",
     "test": "npx kempo-test",
     "test:gui": "npx kempo-test --gui",
     "test:browser": "npx kempo-test -b",

package/spa/.config.json ADDED Viewed

@@ -0,0 +1,15 @@
+{
+  "customRoutes": {
+    "/kempo.css": "../node_modules/kempo-css/dist/kempo.min.css",
+    "/*.html": "./app.html",
+    "/": "./app.html"
+  },
+  "middleware": {
+    "security": {
+      "enabled": true,
+      "headers": {
+        "Cache-Control": "public, max-age=3600"
+      }
+    }
+  }
+}

package/spa/app.html ADDED Viewed

@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en">
+<head>
+	<meta charset="UTF-8">
+	<meta name="viewport" content="width=device-width, initial-scale=1.0">
+	<title>Kempo-Server SPA</title>
+	<link rel="stylesheet" href="/kempo.css" />
+</head>
+<body>
+	<nav>
+		<a href="/">Home</a>
+		<a href="/page1.html">Page 1</a>
+		<a href="/about.html">About</a>
+		<a href="/contact.html">Contact</a>
+		<a href="/settings.html">Settings</a>
+	</nav>
+	<main id="main"></main>
+	<script src="/spa.js"></script>
+</body>
+</html>

package/spa/pages/about.html ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ <h1>About</h1>
2	+ <p>This is an example single-page application powered by Kempo-Server.</p>

package/spa/pages/contact.html ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ <h1>Contact</h1>
2	+ <p>Get in touch at <a href="mailto:hello@example.com">hello@example.com</a>.</p>

package/spa/pages/index.html ADDED Viewed

	@@ -0,0 +1 @@
1	+ <h1>Hello <code>index.html</code></h1>

package/spa/pages/page1.html ADDED Viewed

	@@ -0,0 +1 @@
1	+ <h1>Hello <code>page1.html</code></h1>

package/spa/pages/settings.html ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ <h1>Settings</h1>
2	+ <p>Configure your preferences here.</p>

package/spa/spa.js ADDED Viewed

@@ -0,0 +1,32 @@
+const main = document.getElementById("main");
+const loadPage = path => {
+	const page = (path === "/" || path === "/index.html")
+		? "/pages/index.html"
+		: `/pages${path}`;
+	fetch(page)
+		.then(r => {
+			if(!r.ok) throw new Error(r.status);
+			return r.text();
+		})
+		.then(html => {
+			main.innerHTML = html;
+		})
+		.catch(() => {
+			main.innerHTML = "<h1>Page Not Found</h1>";
+		});
+};
+document.addEventListener("click", e => {
+	const a = e.target.closest("a");
+	if(!a || a.origin !== location.origin) return;
+	e.preventDefault();
+	history.pushState(null, "", a.href);
+	loadPage(a.pathname);
+});
+window.addEventListener("popstate", () => {
+	loadPage(location.pathname);
+});
+loadPage(location.pathname);