defuss-ssg 0.5.1 → 0.6.0

package/README.md

@@ -1,370 +1,323 @@
-<h1 align="center">
+# defuss-ssg
 
-<img src="https://github.com/kyr0/defuss/blob/main/assets/defuss_mascott.png?raw=true" width="100px" />
+Static site generation, request-time dev SSR, file-based endpoints, and production serving for defuss.
 
-<p align="center">
-  
-  <code>defuss-ssg</code>
+`defuss-ssg` is both a CLI and a library:
 
-</p>
+- `dev` starts a Vite server and renders MD/MDX pages on demand through SSR.
+- `build` renders static HTML, bundles client components, compiles endpoints, and copies assets.
+- `serve` serves built output with `defuss-express`, plus dynamic endpoints and optional RPC.
 
-<sup align="center">
+Use Bun for package management. The published package targets Node `^20.19.0 || >=22.12.0`.
 
-Static Site Generator (SSG) for defuss
+## What It Supports
 
-</sup>
+- Markdown and MDX pages from `pages/` or `src/pages/`
+- YAML or TOML frontmatter exposed as `meta`
+- GitHub Flavored Markdown via `remark-gfm`
+- KaTeX math via `$...$` and `$$...$$`
+- defuss components imported into MDX and HTML-like pages
+- Automatic hydration boundaries for components rendered from `components/`, `src/components/`, `csr/`, or `src/csr/`
+- Static assets copied from `assets/` or `src/assets/`
+- File-based API routes from `pages/**/*.ts` and `pages/**/*.js`
+- Root `index.mdx`, `index.md`, or `index.html` fallback when no pages directory exists
+- Pre-rendered endpoints via `prerender = true` and `getStaticPaths()`
+- RPC auto-discovery from `rpc.ts` or `rpc.js` when `defuss-rpc` is installed
+- Plugin hooks for `pre`, `page-vdom`, `page-dom`, `page-html`, and `post`
+- Multicore production serving through `--multicore` or `workers: "auto"`
 
-</h1>
+## Install
 
-<h3 align="center">
-Usage
-</h3>
-
-Simply generate a static site from a content directory to an output directory with full defuss-MDX (GFM + Frontmatter) support:
+Run directly:
 
 ```bash
-bunx defuss-ssg build ./folder
+bunx defuss-ssg build ./my-site
 ```
 
-Or install globally or locally in a project:
+Or add it as a dev dependency:
 
-```bash 
-bun add -g defuss-ssg
+```bash
+bun add -D defuss-ssg
 ```
 
-And then run (in an NPM script or globally):
+## Quick Start
 
-<h4>One-time builds</h4>
-
-```bash
-defuss-ssg build ./folder
+```text
+my-site/
+├-- pages/
+|   ├-- index.mdx
+|   └-- api/
+|       └-- ping.json.ts
+├-- components/
+|   └-- button.tsx
+├-- assets/
+|   └-- styles.css
+├-- config.ts
+└-- rpc.ts
 ```
 
-<h4>Vite-powered development</h4>
+Minimal config:
+
+```ts
+import { rehypePlugins, remarkPlugins, type SsgConfig } from "defuss-ssg";
+
+const config: SsgConfig = {
+	pages: "pages",
+	output: "dist",
+	components: "components",
+	assets: "assets",
+	tmp: ".ssg-temp",
+	plugins: [],
+	remarkPlugins: [...remarkPlugins],
+	rehypePlugins: [...rehypePlugins],
+	rpc: true,
+};
 
-```bash
-defuss-ssg dev ./folder
+export default config;
 ```
 
-This starts a Vite dev server at http://localhost:3000 and watches for changes in:
+Example page:
 
-- `pages/` directory
-- `components/` directory
-- `assets/` directory
+```mdx
+---
+title: Home
+---
 
-Changes trigger automatic rebuilds, with the last change always taking priority to prevent build queueing issues.
+import { Button } from "../components/button.js";
 
-The current migration bridge still writes dev output to `dist/` while the request-time Vite renderer is being moved over.
+# {meta.title}
 
-<h4>Production serving</h4>
+This page uses MDX, frontmatter, and a defuss component.
 
-```bash
-defuss-ssg serve ./folder
+<Button label="Click me" />
 ```
 
-This serves already-built output with `defuss-express`. Run `defuss-ssg build ./folder` first.
+Example component:
 
-<h4>Local development of SSG and running the example</h4>
-
-Unlike other SSG systems, this package is **not** meant to be installed in a project, but rather used as a global CLI tool or programmatically.
+```tsx
+export function Button({ label }: { label: string }) {
+	return <button type="button">{label}</button>;
+}
+```
 
-Developing this means to clone the repo, install dependencies and run the example site:
+Build the site:
 
 ```bash
-git clone https://github.com/kyr0/defuss.git
+defuss-ssg build ./my-site
+```
 
-cd defuss/packages/ssg
+Start Vite-powered development:
 
-bun i && bun build
+```bash
+defuss-ssg dev ./my-site
+```
 
-# for building and serving the example site with auto-rebuild:
-bun run cli-dev ./example
+Serve the already built output:
 
-# for one-time build of the example site:
-bun run cli-build ./example
+```bash
+defuss-ssg serve ./my-site
 ```
 
-Please create a PR or issue if you find any bugs or have feature requests.
+`serve` expects existing build output in `dist/`, so run `build` first.
 
-<h4>Programmatic API</h4>
+## How It Works
 
-Advanced users may want to use the library programmatically:
+### Dev Mode
 
-```typescript
-import { setup, build, dev, serve } from "defuss-ssg";
+`defuss-ssg dev` starts a Vite server rooted at your project. Requests for MD and MDX pages are resolved through Vite's transform pipeline and rendered on demand with SSR. Page, component, endpoint, RPC, config, and asset changes are coalesced before reload. CSS assets are hot-swapped when possible, and hydration boundaries restore local form and scroll state across component updates.
 
-(async () => {
+By default, the CLI keeps `dist/` refreshed during dev as a compatibility fallback for middleware paths. Programmatic users can disable that bridge with `writeDevOutput: false`.
 
-  // Setup project initially
-  const setupStatus = await setup("./my-site");
-  if (setupStatus.code !== "OK") { 
-    console.error("Setup failed:", setupStatus.message);
-    process.exit(1);
-  }
+### Build Mode
 
-  // One-time build
-  await build({
-    projectDir: "./my-site",
-    debug: true,
-  });
+`defuss-ssg build` loads `config.ts`, copies the project into `.ssg-temp`, renders each page through a temporary Vite SSR server, applies automatic hydration wrapping, bundles client components, compiles endpoints into `.endpoints`, copies assets into `dist`, and removes the temp directory unless debug mode is enabled.
 
-  // Or start the Vite-backed dev server
-  await dev({
-    projectDir: "./my-site", 
-    debug: true,
-  });
+### Serve Mode
 
-  // Or serve an already-built production output
-  await serve({
-    projectDir: "./my-site",
-    workers: "auto",
-  });
-})();
-```
+`defuss-ssg serve` reads the built output from `dist/` and serves it with `defuss-express`. Dynamic endpoint modules are registered at runtime, and `rpc.ts` or `rpc.js` is compiled and initialized automatically when RPC is enabled and `defuss-rpc` is installed.
 
-<h3 align="center">
-Overview
-</h3>
+## Endpoints
 
-> `defuss-ssg` is a CLI tool and library for building static websites using modern JavaScript/TypeScript and `defuss`. It reads content files (Markdown, MDX) from a specified directory, processes them with MDX plugins, compiles components with esbuild, and outputs fully static HTML sites ready for deployment.
+Endpoint source files live under `pages/` and export HTTP method handlers.
 
-> It supports a plugin system for extending the build process at various phases (pre-build, post-build, page-level transformations), Vite-backed development, and defuss-express production serving.
+```ts
+import type { APIRoute } from "defuss-ssg";
 
-<h3 align="center">
+export const GET: APIRoute = async () => {
+	return Response.json({ ok: true, ts: Date.now() });
+};
+```
 
-Features
+Supported method exports are `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`, and `ALL`.
 
-</h3>
+Dynamic routes use bracket syntax:
 
-- **MDX Support**: Full Markdown + JSX support with frontmatter parsing
-- **Component Integration**: Use defuss components in your MDX files
-- **Plugin System**: Extend the build process with custom plugins at multiple phases
-- **Fast Compilation**: Powered by esbuild today, with Vite now orchestrating development
-- **Dev Mode**: Vite-backed development server with auto-rebuild and full reload
-- **Production Runtime**: `defuss-express` serves static output plus dynamic endpoints and RPC
-- **TypeScript Ready**: Full TypeScript support for components and configuration
-- **Asset Handling**: Automatic copying of static assets to output directory
-- **Flexible Configuration**: Configurable via TypeScript config file with sensible defaults
+```text
+pages/api/[id].json.ts  ->  /api/:id.json
+pages/feed.xml.ts       ->  /feed.xml
+```
 
-<h3 align="center">
+To pre-render an endpoint during `build`, export `prerender = true`. Dynamic routes can also export `getStaticPaths()`.
 
-Example site project structure
+```ts
+import type { APIRoute } from "defuss-ssg";
 
-</h3>
+export const prerender = true;
 
-Create a project structure like this:
+export const getStaticPaths = () => [
+	{ params: { slug: "hello-world" } },
+	{ params: { slug: "release-notes" } },
+];
 
-```typescript
-my-site/
-├-- pages/
-│   ├-- index.mdx
-│   └-- blog/
-│       └-- hello-world.mdx
-├-- components/
-│   └-- button.tsx
-├-- assets/
-│   └-- styles.css
-└-- config.ts
+export const GET: APIRoute = async ({ params }) => {
+	return new Response(`Post: ${params.slug}`);
+};
 ```
-Then run `defuss-ssg build ./my-site` and a `dist` folder will be created with the complete static build.
 
-<h3 align="center">
+## RPC
 
-Config file
-
-</h3>
-
-You can customize the paths and behaviour of the build process, by creating a simple `config.ts` file in the project folder.
-
-##### Example `config.ts` file
-
-```typescript
-import { remarkPlugins, rehypePlugins } from "defuss-ssg";
+RPC is optional and discovered automatically from `rpc.ts` or `rpc.js` in the project root. Install `defuss-rpc` to enable it.
 
+```ts
 export default {
-  pages: "pages",
-  output: "dist",
-  components: "components",
-  assets: "assets",
-  remarkPlugins: [...remarkPlugins], // default remark plugins
-  rehypePlugins: [...rehypePlugins], // default rehype plugins
-  plugins: [],
+	mathApi: {
+		add: async (a: number, b: number) => a + b,
+	},
+	greetApi: {
+		hello: async (name: string) => `Hello, ${name}!`,
+	},
 };
 ```
 
-You may add any `remark` and `rehype` plugin of your choice. See the `MDX` documentation for more informations on Remark and Rehype.
-
-`defuss-ssg` plugins can be registered via the `plugins` array and are executed in order of registration, in each build phase.
-
-##### Example MDX page (`pages/index.mdx`)
-
-```mdx
----
-title: Home Page
----
+When RPC is active, `defuss-ssg` exposes:
 
-import Button from "../components/button.js"
+- `POST /rpc`
+- `POST /rpc/schema`
 
-# Welcome to my site
+Set `rpc: false` in `config.ts` to disable RPC discovery.
 
-This is a **markdown** page with JSX components.
+## Plugins
 
-<Button>Click me</Button>
-```
+`defuss-ssg` plugins run in build order and can modify the pipeline at distinct phases.
 
-##### Example Button component (`components/button.tsx`)
+```ts
+import type { SsgPlugin } from "defuss-ssg";
 
-Components are imported as `.js` but saved as `.tsx`:
+const htmlStampPlugin: SsgPlugin = {
+	name: "html-stamp",
+	phase: "page-html",
+	mode: "both",
+	fn: (html, relativeOutputHtmlFilePath) => {
+		return html.replace(
+			"</body>",
+			`<!-- built:${relativeOutputHtmlFilePath} --></body>`,
+		);
+	},
+};
 
-```typescript
-export const Button = ({ label }: { label: string }) => {
-  return (
-    <button type="button" onClick={() => alert("Button clicked!")}>
-      {label}
-    </button>
-  );
+export default {
+	plugins: [htmlStampPlugin],
 };
 ```
 
+Available phases:
 
-<h3 align="center">
+- `pre`: before a full build starts
+- `page-vdom`: after page VDOM creation and before render
+- `page-dom`: after DOM render and before serialization
+- `page-html`: after HTML serialization and before write
+- `post`: after the build completes
 
-Plugin System
+`page-vdom` hooks receive the page props/module exports as their fifth argument.
 
-</h3>
+## Programmatic API
 
-Extend the build process with plugins that run at different phases:
+```ts
+import { build, dev, serve, setup } from "defuss-ssg";
 
-```typescript
-import { rule, transval, access } from 'defuss-transval';
+const projectDir = "./my-site";
 
-type UserData = {
-  user: {
-    profile: {
-      name: string;
-      email: string;
-      settings: {
-        theme: 'light' | 'dark';
-        notifications: boolean;
-      };
-    };
-    posts: Array<{
-      title: string;
-      published: boolean;
-    import { SsgPlugin } from "defuss-ssg";
+const setupStatus = await setup(projectDir);
+if (setupStatus.code !== "OK") {
+	throw new Error(setupStatus.message);
+}
 
-const myPlugin: SsgPlugin = {
-  name: "my-plugin",
-  phase: "page-html", // "pre" | "post" | "page-vdom" | "page-dom" | "page-html"
-  fn: (html, relativePath, config) => {
-    // Modify HTML before writing
-    return html.replace("old-text", "new-text");
-  },
-};
+await build({
+	projectDir,
+	mode: "build",
+	debug: true,
+});
 
-export default {
-  plugins: [myPlugin],
-  // ... other config
-};
-```
+await dev({
+	projectDir,
+	port: 3000,
+	host: true,
+	writeDevOutput: true,
+});
 
-Available plugin phases:
+await serve({
+	projectDir,
+	port: 3000,
+	workers: "auto",
+});
+```
 
-- **pre**: Before build starts
-- **page-vdom**: After VDOM creation for each page
-- **page-dom**: After DOM rendering for each page
-- **page-html**: After HTML serialization for each page
-- **post**: After build completes
+The main package exports `build`, `dev`, `serve`, `setup`, config defaults, endpoint types, RPC helpers, and plugin types.
 
+Advanced subpath exports:
 
-<h3 align="center">
+- `defuss-ssg/vite`: exposes `defussSsg()` for custom Vite integration
+- `defuss-ssg/runtime`: exposes the client runtime used for navigation, hydration, and live reload
 
-MDX Features
+Most projects only need the main package export.
 
-</h3>
+## CLI Reference
 
-`defuss-ssg` supports full MDX with `defuss` components and common GFM Markdown features:
+```bash
+defuss-ssg [dev|build|serve] [folder] [--debug] [--multicore]
 
-- **Frontmatter**: YAML/TOML metadata extraction - the `meta` object holds frontmatter data - use e.g. `{ meta.title }` for page title defined in frontmatter like this: 
-```mdx
---- 
-title: My Page 
----
+No args           -> dev .
+Single path       -> dev <path>
+Single command    -> <command> .
+Command + folder  -> <command> <folder>
 ```
 
-- **JSX Components**: Use `defuss` components in your content
-- **Math Support**: KaTeX rendering with `$...$` and `$$...$$`
-- **Custom Plugins**: Extend MDX processing with remark/rehype plugins
-
-<h3 align="center">
+When `pages`, `components`, or `assets` are not configured explicitly, `defuss-ssg` prefers `src/pages`, `src/components`, `src/csr`, and `src/assets` before falling back to their project-root equivalents. If no pages directory exists, it falls back to root `index.mdx`, then `index.md`, then `index.html`.
 
-Build Process
-
-</h3>
+Commands:
 
-The build process follows these steps:
+- `dev`: starts the Vite dev server on port `3000` by default
+- `build`: generates the static site into `dist/`
+- `serve`: serves the built output from `dist/`
 
-1. **Copy Project**: Copy all files to temporary directory
-2. **Compile MDX**: Process MDX files to ESM JavaScript
-3. **Compile Components**: Bundle components with esbuild
-4. **Evaluate Pages**: Run page functions to generate VDOM
-5. **Render HTML**: Convert VDOM to HTML using defuss/server
-6. **Run Plugins**: Execute plugins at various phases
-7. **Copy Assets**: Copy static assets to output
-8. **Clean Up**: Remove temporary files (unless debug mode)
+Flags:
 
-<h3 align="center">
+- `--debug` or `-d`: enable verbose logging
+- `--multicore`: use `workers: "auto"` for `serve`
 
-CLI Reference 
+## Local Package Development
 
-</h3>
+To work on `defuss-ssg` inside this monorepo:
 
 ```bash
-defuss-ssg <command> <folder>
-
-Commands:
-  build <folder>    Build the static site
-  serve <folder>    Serve with auto-rebuild on changes
+git clone https://github.com/kyr0/defuss.git
+cd defuss/packages/ssg
+bun install
+bun run build
+bun run cli-dev
 ```
 
-<h3 align="center">
-Benchmark
-</h3>
+The example project used by the package scripts lives in `../../example-ssg/`.
 
-The following benchmark was performed on the RPC endpoint of the example site, which calls a simple server-side function that adds two numbers. The test was run with 1024 concurrent connections, a pipelining factor of 256, and 8 workers for 30 seconds on a Macbook Air M4, 24 GB RAM under medium load (IDE, browser, docker, Spotify, Mail and terminal running while the benchmark was conducted).
+## Benchmarking
+
+The benchmark scripts are for local experiments, not committed performance guarantees.
 
 ```bash
-$ bun x autocannon -p 256 -w 8 -c 1024 -d 30 -m POST -H 'content-type: application/json' -b '{"className":"mathApi","methodName":"add","args":[1,2]}' http://127.0.0.1:3000/rpc
-Running 30s test @ http://127.0.0.1:3000/rpc
-1024 connections with 256 pipelining factor
-8 workers
-
-/
-┌─────────┬────────┬─────────┬─────────┬─────────┬────────────┬────────────┬─────────┐
-│ Stat    │ 2.5%   │ 50%     │ 97.5%   │ 99%     │ Avg        │ Stdev      │ Max     │
-├─────────┼────────┼─────────┼─────────┼─────────┼────────────┼────────────┼─────────┤
-│ Latency │ 617 ms │ 4708 ms │ 5629 ms │ 6230 ms │ 4367.37 ms │ 1263.71 ms │ 7115 ms │
-└─────────┴────────┴─────────┴─────────┴─────────┴────────────┴────────────┴─────────┘
-┌───────────┬─────────┬─────────┬─────────┬─────────┬──────────┬─────────┬─────────┐
-│ Stat      │ 1%      │ 2.5%    │ 50%     │ 97.5%   │ Avg      │ Stdev   │ Min     │
-├───────────┼─────────┼─────────┼─────────┼─────────┼──────────┼─────────┼─────────┤
-│ Req/Sec   │ 41,215  │ 41,215  │ 54,559  │ 66,751  │ 55,371.2 │ 5,492.3 │ 41,210  │
-├───────────┼─────────┼─────────┼─────────┼─────────┼──────────┼─────────┼─────────┤
-│ Bytes/Sec │ 8.37 MB │ 8.37 MB │ 11.1 MB │ 13.5 MB │ 11.2 MB  │ 1.11 MB │ 8.37 MB │
-└───────────┴─────────┴─────────┴─────────┴─────────┴──────────┴─────────┴─────────┘
-
-Req/Bytes counts sampled once per second.
-# of samples: 240
-
-1923k requests in 30.08s, 337 MB read
+bun run bench
+bun run bench:rpc
 ```
 
-<p align="center">
-
-  <img src="https://raw.githubusercontent.com/kyr0/defuss/refs/heads/main/assets/defuss_comic.png" width="400px" />
-
-</p>
+Benchmark result snapshots are written to `.tmp/bench-results.json` by default. Override that path with `RESULTS_FILE=/path/to/file.json` if needed.
 
-<p align="center">
-  <i><b>Come visit us on <code>defuss</code> Island!</b></i>
-</p>
+For local load-balancing experiments, use `scripts/lb.ts` directly.

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { v as validateProjectDir, b as build } from './vite-B4oPT39d.mjs';
-import { d as dev, s as serve } from './serve-BJ00mBAJ.mjs';
+import { v as validateProjectDir, b as build } from './vite-CaqPNORI.mjs';
+import { d as dev, s as serve } from './serve-Cd4Pw98E.mjs';
 import { join, dirname, resolve } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { spawn } from 'node:child_process';
@@ -173,27 +173,32 @@ Continuing anyway - dependencies may already be available.`
   const debug = args.includes("--debug") || args.includes("-d");
   const multicore = args.includes("--multicore");
   const positional = args.filter((a) => !a.startsWith("-"));
-  const usage = "Usage: defuss-ssg [dev|build|serve] [folder]\n  No args           \u2192 serve .\n  Single path       \u2192 serve <path>\n  Single command    \u2192 <command> .\n  Command + folder  \u2192 <command> <folder>\n  Flags: [--debug] [--multicore]";
+  const commands = /* @__PURE__ */ new Set(["dev", "build", "serve"]);
+  const usage = "Usage: defuss-ssg [dev|build|serve] [folder]\n  No args           => dev .\n  Single path       => dev <path>\n  Single command    => <command> .\n  Command + folder  => <command> <folder>\n  Flags: [--debug] [--multicore]";
   let command;
   let folder;
   if (positional.length === 0) {
-    command = "serve";
+    command = "dev";
     folder = ".";
   } else if (positional.length === 1) {
     const arg = positional[0];
-    if (arg === "dev" || arg === "build" || arg === "serve") {
+    if (commands.has(arg)) {
       command = arg;
       folder = ".";
-    } else if (arg.startsWith(".") || arg.startsWith("/")) {
-      command = "serve";
-      folder = arg;
     } else {
+      command = "dev";
+      folder = arg;
+    }
+  } else if (positional.length === 2) {
+    if (!commands.has(positional[0])) {
       console.error(usage);
       process.exit(1);
     }
-  } else {
     command = positional[0];
     folder = positional[1];
+  } else {
+    console.error(usage);
+    process.exit(1);
   }
   const projectDir = resolve(folder);
   await setup(projectDir);

package/dist/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var vite = require('./vite-DySvB3OP.cjs');
+var vite = require('./vite-CBAZNNYA.cjs');
 var mdx = require('@mdx-js/rollup');
 var vite$1 = require('vite');
 var defuss = require('defuss-vite');