@docubook/flame 1.4.4 → 1.5.0

package/bin/cli.js

@@ -1,18 +1,46 @@
-#!/usr/bin/env bun
-/* global process, console */
+#!/usr/bin/env node
+/* global process, console, Bun, Deno */
 
 import { resolve, join } from "node:path";
+import { pathToFileURL } from "node:url";
 import { cpSync, existsSync, readFileSync, writeFileSync, renameSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 
 const __dirname = import.meta.dirname;
 
+// Runtime detection — override with FLAME_RUNTIME=bun|node|deno for testing.
+const runtime =
+  process.env.FLAME_RUNTIME ||
+  (typeof Bun !== "undefined" ? "bun" : typeof Deno !== "undefined" ? "deno" : "node");
+
 const COMMAND_MAP = {
-  dev: "server.ts",
-  build: "build.ts",
-  clean: "clean.ts",
-  preview: "preview.ts",
-  deploy: "deploy.ts",
-};
+  bun: {
+    dev: "server.ts",
+    build: "build.ts",
+    clean: "clean.ts",
+    preview: "preview.ts",
+    deploy: "deploy.ts",
+  },
+  node: {
+    dev: "server.node.ts",
+    build: "build.node.ts",
+    clean: "clean.ts",
+    preview: "preview.node.ts",
+    deploy: "deploy.node.ts",
+  },
+  deno: {
+    dev: "server.deno.ts",
+    build: "build.deno.ts",
+    clean: "clean.ts",
+    preview: "preview.deno.ts",
+    deploy: "deploy.deno.ts",
+  },
+}[runtime];
+
+if (!COMMAND_MAP) {
+  console.error(`Unknown runtime: "${process.env.FLAME_RUNTIME}" (expected bun, node, or deno)`);
+  process.exit(1);
+}
 
 const command = process.argv[2];
 
@@ -24,7 +52,7 @@ if (themeIndex !== -1 && themeIndex + 1 < process.argv.length) {
 
 if (!command || command === "--help" || command === "-h") {
   console.log(`
-  @docubook/flame — A blazing-fast React + MDX framework powered by Bun, built for modern documentation experiences.
+  @docubook/flame — A blazing-fast React + MDX framework for modern documentation experiences. Runs on Bun, Node.js, and Deno.
 
   Usage: flame <command>
 
@@ -70,9 +98,24 @@ if (command === "init") {
     const flamePkg = JSON.parse(readFileSync(resolve(__dirname, "../package.json"), "utf-8"));
     pkg.dependencies = pkg.dependencies || {};
     pkg.dependencies["@docubook/flame"] = `^${flamePkg.version}`;
+    if (runtime === "deno") {
+      // Deno has no node_modules/.bin — tasks must call flame via npm: specifier.
+      const flameCmd = "deno run -A npm:@docubook/flame";
+      pkg.scripts = {
+        dev: `${flameCmd} dev`,
+        build: `${flameCmd} build`,
+        preview: `${flameCmd} preview`,
+        deploy: `${flameCmd} deploy`,
+      };
+    }
     writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 
-    console.log(`\n  ✓ Project scaffolded!\n\n  Next steps:\n    bun install\n    bun run dev\n`);
+    const nextSteps = {
+      bun: "    bun install\n    bun run dev",
+      node: "    npm install\n    npm run dev",
+      deno: "    deno task dev",
+    }[runtime];
+    console.log(`\n  ✓ Project scaffolded!\n\n  Next steps:\n${nextSteps}\n`);
     process.exit(0);
   } catch (err) {
     console.error(`Failed to scaffold project: ${err.message}`);
@@ -85,7 +128,39 @@ if (!(command in COMMAND_MAP)) {
   process.exit(1);
 }
 
-const nodePath = resolve(__dirname, "../.docu/node", COMMAND_MAP[command]);
-const libPath = resolve(__dirname, "../.docu/lib", COMMAND_MAP[command]);
-const scriptPath = existsSync(nodePath) ? nodePath : libPath;
-await import(scriptPath);
+const sourceFile = COMMAND_MAP[command];
+const packageRoot = resolve(__dirname, "..");
+const nodePath = join(packageRoot, ".docu/node", sourceFile);
+const libPath = join(packageRoot, ".docu/lib", sourceFile.replace(/\.ts$/, ".js"));
+
+// Bun executes TypeScript sources directly; Node and Deno use the
+// precompiled JS in .docu/lib, generated at publish. In a monorepo clone
+// .docu/lib is gitignored, so compile it lazily — the entry graph imports
+// .tsx sources that Node cannot load.
+if (runtime !== "bun" && !existsSync(libPath) && existsSync(nodePath)) {
+  console.log("flame: .docu/lib missing — precompiling entry points...");
+  const compileScript = join(__dirname, "compile-lib.mjs");
+  const result = spawnSync(
+    process.execPath,
+    typeof Deno === "undefined" ? [compileScript] : ["run", "-A", compileScript],
+    { cwd: packageRoot, stdio: "inherit" }
+  );
+  if (result.status !== 0) {
+    console.error(
+      result.error
+        ? `flame: failed to run compile-lib.mjs: ${result.error.message}`
+        : "flame: failed to precompile .docu/lib (see output above)."
+    );
+    process.exit(result.status ?? 1);
+  }
+}
+
+const scriptPath =
+  runtime === "bun"
+    ? existsSync(nodePath)
+      ? nodePath
+      : libPath
+    : existsSync(libPath)
+      ? libPath
+      : nodePath;
+await import(pathToFileURL(scriptPath).href);

package/bin/compile-lib.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * Precompile the Node/Deno entry points to plain ESM JavaScript in
+ * `.docu/lib/`. Node cannot import `.ts`/`.tsx` sources and Deno does not
+ * execute TypeScript inside npm packages, so the published package ships
+ * this compiled tree alongside the Bun-executed TypeScript in `.docu/node/`.
+ * The CLI routes non-Bun runtimes here (see `bin/cli.js`).
+ */
+
+import { rmSync } from "node:fs";
+import { build, stop } from "esbuild";
+
+const ENTRIES = [
+  "server.node.ts",
+  "server.deno.ts",
+  "build.node.ts",
+  "build.deno.ts",
+  "preview.node.ts",
+  "preview.deno.ts",
+  "deploy.node.ts",
+  "deploy.deno.ts",
+  "clean.ts",
+];
+
+rmSync(".docu/lib", { recursive: true, force: true });
+
+await build({
+  entryPoints: ENTRIES.map((entry) => `.docu/node/${entry}`),
+  outdir: ".docu/lib",
+  bundle: true,
+  splitting: true,
+  format: "esm",
+  platform: "node",
+  target: "node20",
+  packages: "external",
+  jsx: "automatic",
+  logLevel: "info",
+  plugins: [
+    {
+      // The SSR component graph imports `docu.json` statically
+      // (client-routes.ts). At runtime that must be the USER's project
+      // config, so replace the import with a cwd-relative read instead of
+      // baking the monorepo's docu.json into the published bundle.
+      name: "docu-config-runtime",
+      setup(build) {
+        build.onResolve({ filter: /docu\.json$/ }, (args) => ({
+          path: args.path,
+          namespace: "docu-config-runtime",
+        }));
+        build.onLoad({ filter: /.*/, namespace: "docu-config-runtime" }, () => ({
+          contents: [
+            `import { readFileSync } from "node:fs";`,
+            `import { join } from "node:path";`,
+            `const config = JSON.parse(readFileSync(join(process.cwd(), "docu.json"), "utf-8"));`,
+            `export default config;`,
+          ].join("\n"),
+          loader: "js",
+        }));
+      },
+    },
+  ],
+});
+
+// esbuild's service process keeps Deno's event loop alive after one-shot
+// build() calls — stop it explicitly so `flame` can invoke this script
+// under Deno. Harmless under Node.
+await stop();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docubook/flame",
-  "version": "1.4.4",
+  "version": "1.5.0",
   "description": "A blazing-fast React + MDX framework powered by Bun, built for modern documentation experiences.",
   "type": "module",
   "bin": {
@@ -22,6 +22,7 @@
     "access": "public"
   },
   "engines": {
+    "node": ">=20.11",
     "bun": ">=1.1.0"
   },
   "keywords": [
@@ -48,14 +49,16 @@
     "@tailwindcss/typography": "0.5.16",
     "bun-plugin-tailwind": "^0.1.2",
     "daisyui": "^5.5.19",
+    "esbuild": "^0.28.1",
     "lucide-react": "^1.14.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "unified": "^11.0.0",
-    "@docubook/ui-react": "^0.1.4",
-    "@docubook/mdx-content": "^3.4.1",
-    "@docubook/core": "^1.8.0",
-    "@docubook/themes-colors": "^0.10.2"
+    "@docubook/core": "^1.8.1",
+    "@docubook/mdx-content": "^3.4.2",
+    "@docubook/runt": "^1.0.0",
+    "@docubook/themes-colors": "^1.0.0",
+    "@docubook/ui-react": "^1.0.0"
   },
   "peerDependencies": {
     "@sentry/bun": "^10.0.0"
@@ -87,6 +90,7 @@
     "clean": "bun .docu/node/clean.ts",
     "preview": "bun .docu/node/preview.ts",
     "deploy": "bun .docu/node/deploy.ts",
+    "compile:lib": "node bin/compile-lib.mjs",
     "test": "vitest run",
     "lint": "eslint ."
   }

package/template/docs/getting-started/configuration.mdx

@@ -0,0 +1,18 @@
+---
+title: Configuration
+description: docu.json reference — meta, navbar, themes, routes, and plugins.
+---
+
+`docu.json` in your project root controls the site. Key sections:
+
+| Field | Description |
+|---|---|
+| `meta` | Site title, description, favicon, base URL |
+| `navbar` | Logo, navigation menu links |
+| `home.hero` | Landing page hero with tagline, headline, actions |
+| `home.features` | Feature cards with icon, title, description |
+| `routes` | Sidebar navigation (auto-detected from `docs/` when empty) |
+| `themes` | Colour preset or custom palette |
+| `plugins` | Build/dev pipeline extensions |
+
+See this site's `docu.json` for a complete example, or refer to `docu.schema.json` in the package root.

package/template/docs/getting-started/overview.mdx

@@ -0,0 +1,50 @@
+---
+title: Quick Start
+description: Get your first documentation site running on Bun, Node.js, or Deno.
+---
+
+## Prerequisites
+
+Choose **one** runtime:
+
+- **Bun** >= 1.1: `curl -fsSL https://bun.sh/install | bash`
+- **Node.js** >= 20.11: [nodejs.org](https://nodejs.org)
+- **Deno** >= 2.x: `curl -fsSL https://deno.land/install.sh | sh`
+
+## Create a project
+
+<Tabs>
+  <Tab title="Bun">
+    ```bash
+    mkdir my-docs && cd my-docs
+    bun add @docubook/flame
+    bunx flame init
+    bun run dev
+    ```
+  </Tab>
+  <Tab title="Node.js">
+    ```bash
+    mkdir my-docs && cd my-docs
+    npm install @docubook/flame
+    npx flame init
+    npm run dev
+    ```
+  </Tab>
+  <Tab title="Deno">
+    ```bash
+    mkdir my-docs && cd my-docs
+    deno run -A npm:@docubook/flame init
+    deno task dev
+    ```
+  </Tab>
+</Tabs>
+
+Open http://localhost:3000 — changes to `docs/` or `docu.json` hot-reload.
+
+## Build for production
+
+```bash
+npm run build     # or: bun run build / deno task build
+```
+
+Static output goes to `.docu/dist/` — deploy to any CDN or static host.

package/template/docs/guide/deployment.mdx

@@ -0,0 +1,27 @@
+---
+title: Deployment
+description: Deploy your Flame site to any static host.
+---
+
+Flame produces **flat static HTML** — no server, no database, no runtime required. Deploy the output of `.docu/dist/` to any CDN or static host.
+
+## GitHub Pages
+
+```bash
+npm run deploy
+```
+
+This builds the site, adds `.nojekyll`, and generates a GitHub Actions workflow on first run.
+
+## Manual
+
+```bash
+npm run build
+```
+
+Upload `.docu/dist/` to any of:
+
+- **Vercel** — drop the folder or connect your repo
+- **Netlify** — publish directory: `.docu/dist`
+- **Cloudflare Pages** — output directory: `.docu/dist`
+- **S3 / GCS / Azure** — sync and serve via CDN

package/template/docs/guide/routing.mdx

@@ -0,0 +1,25 @@
+---
+title: Routing
+description: How Flame maps MDX files to static HTML pages.
+---
+
+Flame uses **filesystem-based routing** — every `.mdx` file in `docs/` compiles to a matching `.html` path:
+
+```
+docs/
+├── index.mdx                       → /docs/index.html
+├── getting-started/
+│   ├── overview.mdx                → /docs/getting-started/overview.html
+│   └── configuration.mdx           → /docs/getting-started/configuration.html
+└── guide/
+    ├── components.mdx              → /docs/guide/components.html
+    └── routing.mdx                 → /docs/guide/routing.html
+```
+
+## Auto-routing
+
+When `routes: []` in `docu.json`, Flame automatically scans `docs/` at build time and generates the sidebar from the directory structure.
+
+## Manual routes
+
+Define `routes` in `docu.json` for a custom sidebar. Add `context` groups with icons for multi-section documentation. See this project's `docu.json` for examples.

package/template/docs/index.mdx

@@ -1,212 +1,15 @@
 ---
 title: DocuBook Flame 🔥
-description: Fast as flame — a Bun-native framework for modern documentation experiences.
-date: 2026-05-24
+description: An open-source alternative to Mintlify or GitBook — MDX-powered documentation, static HTML output.
 ---
 
-**@docubook/flame** is a lightweight runtime for building documentation websites using React, MDX, and filesystem-based routing — all running on Bun.
+**@docubook/flame** is a static site generator for documentation. Write in MDX, compile to flat static HTML — no server required. Runs on **Bun**, **Node.js**, and **Deno**.
 
-No heavy abstractions. No complex tooling. Just a minimal layer between your content and the browser.
-
-> **Lightweight** — 📦 ~57 kB packed, ~207 kB unpacked. No bloat, just fire.
-
-## Features
-
-- **Bun-native** — instant startup, native TypeScript, fast builds
-- **React-first** — JSX/TSX, hooks, component composition
-- **MDX content** — write Markdown with embedded React components
-- **Filesystem routing** — auto-detect routes from `docs/` folder
-- **Lightweight SSR** — React server-side rendering without a heavy framework
-- **Client hydration** — interactive islands for sidebar, TOC, and MDX components
-- **HMR** — instant reload on docs changes during development
-- **Static build** — pre-render all pages to static HTML for deployment
-
-## Quick Start
-
-```bash
-mkdir my-docs && cd my-docs
-bun add @docubook/flame
-bunx flame init
-bun run dev
-```
-
-## Project Structure
-
-After `flame init`, your project looks like:
-
-```
-my-docs/
-├── docs/              # Your MDX content
-│   └── index.mdx     # Home page
-├── docu.json          # Site configuration (navbar, routes, meta)
-├── package.json       # Dependencies
-└── .docu/
-    └── dist/          # Build output (after `bun run build`)
-```
-
-## Commands
-
-```bash
-bun run dev       # Start dev server with HMR
-bun run build     # Static build to .docu/dist/
-bun run preview   # Serve built output locally
-bun run deploy    # Build + prepare for GitHub Pages
-```
-
-## Configuration
-
-`docu.json` controls your site:
-
-```json
-{
-  "meta": {
-    "title": "My Docs",
-    "description": "Documentation powered by DocuBook Flame"
-  },
-  "navbar": {
-    "logoText": "My Docs",
-    "menu": [
-      { "title": "Home", "href": "/" },
-      { "title": "Docs", "href": "/docs" }
-    ]
-  },
-  "routes": []
-}
+```mermaid
+flowchart LR
+    A[Your .mdx content] --> B[flame build]
+    B --> C[Static HTML + assets]
+    C --> D[Vercel / Netlify / GitHub Pages / S3]
 ```
 
-### Routes
-
-When `routes` is an empty array `[]`, Flame automatically scans your `docs/` folder at build-time and generates the sidebar navigation from the directory structure. Folders become collapsible sections, and `.mdx`/`.md` files become links — sorted alphabetically.
-
-To define navigation manually, populate the `routes` array:
-
-```json
-{
-  "routes": [
-    {
-      "title": "Getting Started",
-      "href": "/getting-started",
-      "noLink": true,
-      "context": {
-        "icon": "BookOpen",
-        "title": "Guides",
-        "description": "Set up your Documentation"
-      },
-      "items": [
-        { "title": "Introduction", "href": "/introduction" },
-        { "title": "Installation", "href": "/installation" }
-      ]
-    }
-  ]
-}
-```
-
-> Manual routes take priority — if `routes` has entries, folder scanning is skipped entirely.
-
-## Routing
-
-```
-docs/
-├── index.mdx                    → /docs
-├── getting-started/
-│   ├── introduction.mdx         → /docs/getting-started/introduction
-│   └── installation.mdx         → /docs/getting-started/installation
-└── components/
-    ├── button.mdx               → /docs/components/button
-    └── card.mdx                 → /docs/components/card
-```
-
-## Assets
-
-Place images and static files in `docs/assets/`. They are copied to the build output and accessible at `/docs/assets/`.
-
-```
-docs/
-├── assets/
-│   └── images/
-│       ├── logo.svg
-│       └── screenshot.png
-└── getting-started/
-    └── introduction.mdx
-```
-
-Reference in MDX:
-
-```markdown
-![Screenshot](/docs/assets/images/screenshot.png)
-```
-
-> The `docs/assets/` directory is excluded from route scanning — files inside it won't appear in the sidebar.
-
-## Architecture
-
-- **Bun** — runtime, bundler, file watcher
-- **React + React DOM** — rendering (SSR + client hydration)
-- **@docubook/core** — MDX compilation, rehype/remark plugins
-- **@docubook/mdx-content** — pre-built MDX components
-- **Tailwind CSS + daisyUI** — styling
-
-## Comparison
-
-|      Framework      | Runtime |    UI     |          Approach           |
-| ------------------- | ------- | --------- | --------------------------- |
-| Docusaurus          | Node.js | React     | Full-featured, plugin-heavy |
-| VitePress           | Node.js | Vue       | Lightweight, Vue-only       |
-| Nextra              | Node.js | React     | Next.js-based               |
-| **@docubook/flame** | **Bun** | **React** | **Minimal, Bun-native SSR** |
-
-## Deployment
-
-### GitHub Pages
-
-```bash
-bun run deploy
-```
-
-This will:
-
-1. Run production build → output to `.docu/dist/`
-2. Add `.nojekyll` file
-3. Generate `.github/workflows/deploy.yml` (first run only)
-
-Then push to GitHub and enable Pages: **Settings → Pages → Source: GitHub Actions**
-
-### Manual / Other Hosts
-
-```bash
-bun run build
-```
-
-Upload the contents of `.docu/dist/` to any static hosting (Netlify, Cloudflare Pages, Vercel, S3, etc).
-
-## Environment Variables
-
-Copy `.env.example` to `.env` to customize:
-
-```
-# Server port (default: 3000)
-PORT=3000
-
-# Error Monitoring (optional)
-SENTRY_DSN=https://your-dsn@sentry.io/project-id
-```
-
-## Error Monitoring (Optional)
-
-Flame has built-in [Sentry](https://sentry.io) support for error tracking. To enable:
-
-```bash
-bun add @sentry/bun
-```
-
-Then set environment variables:
-
-```
-SENTRY_DSN=https://your-dsn@sentry.io/project-id
-```
-
-Errors during dev server and build will be automatically captured. No configuration needed beyond the DSN.
-
-## Requirements
-
-- [Bun](https://bun.sh) >= 1.1.0
+Check the sidebar for guides on getting started, configuration, components, routing, and deployment.

package/template/docu.json

@@ -74,5 +74,36 @@
     "path": "blob/main/{filePath}",
     "edit": false
   },
-  "routes": []
+  "sidebar": {
+    "context": "dropdown"
+  },
+  "routes": [
+    {
+      "title": "Getting Started",
+      "href": "/getting-started",
+      "noLink": true,
+      "context": {
+        "icon": "Rocket",
+        "title": "Getting Started"
+      },
+      "items": [
+        { "title": "Overview", "href": "/overview" },
+        { "title": "Configuration", "href": "/configuration" }
+      ]
+    },
+    {
+      "title": "Guide",
+      "href": "/guide",
+      "noLink": true,
+      "context": {
+        "icon": "BookOpen",
+        "title": "Guide"
+      },
+      "items": [
+        { "title": "Components", "href": "/components" },
+        { "title": "Routing", "href": "/routing" },
+        { "title": "Deployment", "href": "/deployment" }
+      ]
+    }
+  ]
 }