defuss-ssg 0.6.3 → 0.7.1

package/README.md

@@ -8,7 +8,7 @@ Static site generation, request-time dev SSR, file-based endpoints, and producti
 - `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.
 
-Use Bun for package management. The published package targets Node `^20.19.0 || >=22.12.0`.
+Use Bun for package management. The published package and the container runtime both target Node `^20.19.0 || >=22.12.0`.
 
 ## What It Supports
 
@@ -62,6 +62,7 @@ Minimal config:
 ```ts
 import { rehypePlugins, remarkPlugins, type SsgConfig } from "defuss-ssg";
 
+// all of the fields are optional; you can also skip the file itself!
 const config: SsgConfig = {
 	pages: "pages",
 	output: "dist",
@@ -72,11 +73,44 @@ const config: SsgConfig = {
 	remarkPlugins: [...remarkPlugins],
 	rehypePlugins: [...rehypePlugins],
 	rpc: true,
+  // e.g. set defuss-ssg to use podman even if docker is available
+  containerRuntime: "docker",
+  // override Vite config
+	viteConfig: {
+    ...
+	},
+} satisfies SsgConfig;
+
+export default config;
+```
+
+`containerRuntime` forces `docker` or `podman` for `docker-*` commands. `viteConfig` is merged into defuss-ssg's internal Vite config for both `dev` and `build`, so you can add aliases, plugins, server options, and similar Vite settings from `config.ts`.
+
+If you need to extend the current defuss-ssg Vite config instead of only passing a patch object, import it from the virtual module and merge from there:
+
+```ts
+import { mergeConfig } from "vite";
+import { viteConfig as currentViteConfig } from "virtual:defuss-ssg/config";
+
+const config: SsgConfig = {
+	viteConfig: mergeConfig(currentViteConfig, {
+		resolve: {
+			alias: {
+				"@app": new URL("./src", import.meta.url).pathname,
+			},
+		},
+    server: {
+      // your custom domain, headers etc.
+      allowedHosts: ["example-ssg.demo.defuss.tech"],
+    },
+	}),
 };
 
 export default config;
 ```
 
+The virtual module resolves to the current internal `defuss-ssg` Vite config, so you can also inspect or extend existing plugin arrays and nested Vite settings without re-creating them manually.
+
 Example page:
 
 ```mdx
@@ -96,8 +130,16 @@ This page uses MDX, frontmatter, and a defuss component.
 Example component:
 
 ```tsx
-export function Button({ label }: { label: string }) {
-	return <button type="button">{label}</button>;
+import type { Props } from "defuss";
+
+export interface ButtonProps extends Props {
+  label: string;
+}
+
+export function Button({ label }: ButtonProps) {
+	return (
+    <button type="button">{label}</button>
+  );
 }
 ```
 
@@ -121,6 +163,61 @@ defuss-ssg serve ./my-site
 
 `serve` expects existing build output in `dist/`, so run `build` first.
 
+For checked-out, unpublished, or locally linked package development use e.g.:
+
+```bash
+node ./dist/cli.mjs dev ../../examples/with-dson/ --port 3010
+```
+
+
+## Production Deployment
+
+`defuss-ssg` supports `podman` and `docker` for production deployment.
+
+The primary container workflow is built into the CLI:
+
+```bash
+bunx defuss-ssg container-dev ./my-site
+bunx defuss-ssg container-build ./my-site
+bunx defuss-ssg container-serve ./my-site --multicore
+```
+
+When you are working from this monorepo before the next npm publish, use the built local CLI instead of `bunx defuss-ssg`. `bunx defuss-ssg` resolves the last published package, so it will not see unreleased `docker-*` commands from this checkout:
+
+```bash
+cd packages/ssg
+bun run build
+node ./dist/cli.mjs container-dev ../../example-ssg --port 3111 --container-args --network host
+```
+
+Each `docker-*` command writes a temporary Dockerfile, builds a local `defuss-ssg` image, mounts your project at `/workspace`, mounts a deterministic container-managed `/workspace/node_modules` volume, and then runs the matching inner `defuss-ssg` command. The mounted project still owns its dependency graph: the container reads that project's `package.json`, uses its declared package manager, installs the project's dependencies, and then starts `dev`, `build`, or `serve`.
+
+`container-dev` and `container-serve` automatically bind the inner service to `0.0.0.0` and publish the selected port. One published port is enough even with `--multicore`; `defuss-express` keeps worker ports internal and load-balances behind the public port.
+
+Runtime selection:
+
+- `docker` is preferred automatically when available
+- `podman` is used automatically when Docker is unavailable
+- Set `containerRuntime` in `config.ts` to force one runtime explicitly
+
+```ts
+export default {
+	containerRuntime: "podman",
+};
+```
+
+Outer container runtime arguments can be forwarded with `--container-args`. Everything after that marker is appended to the outer `docker run` or `podman run` call, while the arguments before it still go to the inner `defuss-ssg` command:
+
+```bash
+bunx defuss-ssg container-dev ./my-site --port 3000 --container-args --network host
+bunx defuss-ssg container-serve ./my-site --multicore --container-args --env NODE_ENV=production
+```
+
+Good to know:
+- The container runs the same `setup()` flow as local CLI usage.
+- Use the generated container-managed `/workspace/node_modules` volume instead of bind-mounting host `node_modules` across OS or architecture boundaries.
+- For manual container management, a static, minimal Dockerfile is available as `Dockerfile` too.
+
 ## How It Works
 
 ### Dev Mode
@@ -137,6 +234,45 @@ By default, the CLI keeps `dist/` refreshed during dev as a compatibility fallba
 
 `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.
 
+## Content Discovery
+
+For generation-time listings such as blog archives, `defuss-ssg` now exposes a small `glob()` API.
+
+Use the virtual module inside MDX or other code that Vite evaluates for SSR:
+
+```ts
+import { glob } from "virtual:defuss-ssg/content";
+
+export const posts = (await glob("pages/blog/**/*.mdx")).sort((left, right) =>
+	String(right.meta.date || "").localeCompare(String(left.meta.date || "")),
+);
+```
+
+Use the direct package export in non-Vite server-side contexts such as `config.ts` or custom plugins:
+
+```ts
+import { glob } from "defuss-ssg";
+
+const posts = await glob("pages/blog/**/*.mdx", {
+	cwd: process.cwd(),
+});
+```
+
+Each entry contains:
+
+- `filePath`: absolute file path
+- `relativePath`: path relative to `cwd`
+- `slug`: route-like identifier without a leading slash
+- `route`: public route when the file lives under the configured `pages` directory
+- `meta`: parsed YAML or TOML frontmatter
+
+Notes:
+
+- `cwd` defaults to the current working directory for the direct helper.
+- The virtual module binds `cwd` and `pages` to the active SSG project automatically.
+- `route` is only derived for files inside the configured `pages` directory.
+- Returns metadata records only; it does not eagerly execute every matched MDX module.
+
 ## Endpoints
 
 Endpoint source files live under `pages/` and export HTTP method handlers.
@@ -195,9 +331,19 @@ When RPC is active, `defuss-ssg` exposes:
 - `POST /rpc`
 - `POST /rpc/schema`
 
-Set `rpc: false` in `config.ts` to disable RPC discovery.
+Set `rpc: false` in `config.ts` to disable RPC auto-discovery.
+
+To use the RPC in your client components, import the generated client helper:
+
+```ts
+import { createRpcClient } from "defuss-ssg/rpc";
+
+const rpc = createRpcClient();
+const sum = await rpc.mathApi.add(2, 3);
+console.log(sum); // 5
+```
 
-## Plugins
+## Custom MDX plugins
 
 `defuss-ssg` plugins run in build order and can modify the pipeline at distinct phases.
 
@@ -275,7 +421,7 @@ Most projects only need the main package export.
 ## CLI Reference
 
 ```bash
-defuss-ssg [dev|build|serve] [folder] [--debug] [--multicore]
+defuss-ssg [dev|build|serve|container-dev|container-build|container-serve] [folder] [options]
 
 No args           -> dev .
 Single path       -> dev <path>
@@ -290,11 +436,18 @@ Commands:
 - `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/`
+- `container-dev`: builds the generated image, mounts the project, and starts `dev` inside Docker or Podman
+- `container-build`: builds the generated image, mounts the project, and runs `build` inside Docker or Podman
+- `container-serve`: builds the generated image, mounts the project, and runs `serve` inside Docker or Podman
 
 Flags:
 
 - `--debug` or `-d`: enable verbose logging
 - `--multicore`: use `workers: "auto"` for `serve`
+- `--host` or `-H <host>`: override the dev or serve bind host
+- `--port` or `-p <port>`: override the dev or serve port
+- `--skip-setup` or `--no-setup`: skip project dependency installation for prepared environments and containers
+- `--container-args <args...>`: forward everything after the marker to the outer `docker run` or `podman run` invocation used by `docker-*`
 
 ## Local Package Development