orga-build 0.4.0 → 0.5.1

package/README.org

@@ -2,12 +2,96 @@
 
 A simple tool that builds org-mode files into a website.
 
+* Architecture
+
+orga-build is built on top of Vite with a Vite-native architecture. The dev server uses Vite's native =createServer().listen()= pattern (no custom Express wrapper), which ensures maximum compatibility with the Vite ecosystem, including plugins like Cloudflare Workers.
+
+** Key Design Principles
+
+- *Vite-native*: Framework behavior is implemented as Vite plugins, not external server wrappers
+- *Zero-config*: Works with just =.org= files - no =index.html= required
+- *Plugin-driven*: All features are implemented as composable Vite plugins
+
+** Plugin Composition
+
+When using orga-build CLI with additional Vite plugins (like Cloudflare Workers), add them to =vitePlugins= in your =orga.config.js=:
+
+#+begin_src javascript
+// orga.config.js
+import { cloudflare } from '@cloudflare/vite-plugin'
+
+export default {
+  root: 'pages',
+  // Add external plugins here - orga-build plugins are included automatically
+  vitePlugins: [
+    cloudflare()
+  ]
+}
+#+end_src
+
+Note: Do NOT add =orgaBuildPlugin()= to =vitePlugins= - it's already included by the CLI. Only add external plugins.
+
+For advanced users integrating directly with Vite (without the orga-build CLI), use =orgaBuildPlugin= in your =vite.config.js=:
+
+#+begin_src javascript
+// vite.config.js (advanced - direct Vite integration)
+import { cloudflare } from '@cloudflare/vite-plugin'
+import { orgaBuildPlugin, alias } from 'orga-build'
+
+export default {
+  plugins: [
+    cloudflare(),
+    ...orgaBuildPlugin({ root: 'pages', containerClass: [] })
+  ],
+  resolve: { alias }
+}
+#+end_src
+
+** Default HTML Template
+
+If your project doesn't have an =index.html= file, orga-build provides a default template that:
+- Sets up React rendering
+- Enables client-side routing
+- Works in both dev and production builds
+
+To customize the HTML shell, create your own =index.html= in your project root.
+
 * Installation
 
 #+begin_src bash
 npm install orga-build
 #+end_src
 
+* Configuration
+
+orga-build uses =orga.config.js= (or =orga.config.mjs=) as the primary configuration file. This file should be placed in your project root.
+
+#+begin_src javascript
+// orga.config.js
+export default {
+  // Directory containing your .org files (default: 'pages')
+  root: 'pages',
+
+  // Output directory for production build (default: 'out')
+  outDir: 'out',
+
+  // CSS class(es) to wrap rendered org content
+  containerClass: ['prose', 'prose-lg'],
+
+  // Additional Vite plugins
+  vitePlugins: []
+}
+#+end_src
+
+** Configuration Options
+
+| Option | Type | Default | Description |
+|--------+------+---------+-------------|
+| =root= | =string= | ='pages'= | Directory containing content files |
+| =outDir= | =string= | ='out'= | Output directory for production build |
+| =containerClass= | =string \vert string[]= | =[]= | CSS class(es) for content wrapper |
+| =vitePlugins= | =PluginOption[]= | =[]= | Additional Vite plugins |
+
 * TypeScript Setup
 
 If you're using TypeScript and want type support for the =orga-build:content= virtual module, you need to add a reference to the type definitions.

package/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { argv, cwd } from 'node:process'
+import { argv } from 'node:process'
 import { parseArgs } from 'node:util'
 import { loadConfig } from './lib/config.js'
 import { build } from './lib/build.js'
@@ -10,12 +10,12 @@ const { positionals } = parseArgs({
 	args: argv.slice(2),
 	options: {
 		watch: { type: 'boolean', short: 'w' },
-		outDir: { type: 'string', short: 'o', default: 'out' }
+		outDir: { type: 'string', short: 'o', default: '.out' }
 	},
 	tokens: true,
 	allowPositionals: true
 })
 
-const config = await loadConfig(cwd(), 'orga.config.js', 'orga.config.mjs')
+const config = await loadConfig('orga.config.js', 'orga.config.mjs')
 
 await (positionals.includes('dev') ? serve(config) : build(config))

package/index.d.ts

@@ -1,2 +1,3 @@
 export { build } from "./lib/build.js";
+export { orgaBuildPlugin, createOrgaBuildConfig, alias } from "./lib/plugin.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1 +1,2 @@
 export { build } from './lib/build.js'
+export { orgaBuildPlugin, createOrgaBuildConfig, alias } from './lib/plugin.js'

package/lib/__tests__/build.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=build.test.d.ts.map

package/lib/__tests__/build.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.test.d.ts","sourceRoot":"","sources":["build.test.js"],"names":[],"mappings":""}

package/lib/__tests__/build.test.js

@@ -0,0 +1,64 @@
+import { test, describe, before, after } from 'node:test'
+import assert from 'node:assert'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { build } from '../build.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const fixtureDir = path.join(__dirname, 'fixtures')
+const outDir = path.join(__dirname, '.test-output')
+
+describe('orga-build', () => {
+	before(async () => {
+		await fs.mkdir(fixtureDir, { recursive: true })
+		// Create minimal fixture
+		await fs.writeFile(
+			path.join(fixtureDir, 'index.org'),
+			`#+title: Test Page
+
+* Hello World
+
+This is a test page.
+`
+		)
+	})
+
+	after(async () => {
+		await fs.rm(outDir, { recursive: true, force: true })
+		await fs.rm(fixtureDir, { recursive: true, force: true })
+	})
+
+	test('builds org files to HTML', async () => {
+		await build({
+			root: fixtureDir,
+			outDir: outDir,
+			containerClass: [],
+			vitePlugins: [],
+			preBuild: [],
+			postBuild: []
+		})
+
+		// Check output exists
+		const indexPath = path.join(outDir, 'index.html')
+		const indexExists = await fs
+			.access(indexPath)
+			.then(() => true)
+			.catch(() => false)
+		assert.ok(indexExists, 'index.html should exist')
+
+		// Check content
+		const html = await fs.readFile(indexPath, 'utf-8')
+		assert.ok(html.includes('<title>Test Page</title>'), 'should have title')
+		assert.ok(html.includes('Hello World'), 'should have heading content')
+	})
+
+	test('generates assets directory', async () => {
+		const assetsDir = path.join(outDir, 'assets')
+		const assetsExists = await fs
+			.access(assetsDir)
+			.then(() => true)
+			.catch(() => false)
+		assert.ok(assetsExists, 'assets directory should exist')
+	})
+})

package/lib/build.d.ts

@@ -2,9 +2,6 @@
  * @param {import('./config.js').Config} config
  */
 export function build({ outDir, root, containerClass, vitePlugins }: import("./config.js").Config): Promise<void>;
-export const alias: {
-    react: string;
-    'react-dom': string;
-    wouter: string;
-};
+export { alias };
+import { alias } from './plugin.js';
 //# sourceMappingURL=build.d.ts.map

package/lib/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["build.js"],"names":[],"mappings":"AAmBA;;GAEG;AACH,qEAFW,OAAO,aAAa,EAAE,MAAM,iBA8JtC;AArKD;;;;EAIC"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["build.js"],"names":[],"mappings":"AAcA;;GAEG;AACH,qEAFW,OAAO,aAAa,EAAE,MAAM,iBAqJtC;;sBA/J4C,aAAa"}

package/lib/build.js

@@ -1,21 +1,16 @@
 import path from 'node:path'
-import { createRequire } from 'node:module'
-import { build as viteBuild } from 'vite'
-import { setupOrga } from './orga.js'
-import react from '@vitejs/plugin-react'
+import { createBuilder } from 'vite'
 import { fileURLToPath, pathToFileURL } from 'node:url'
-import { copy, emptyDir, ensureDir } from './fs.js'
-import { pluginFactory } from './vite.js'
+import { copy, emptyDir, ensureDir, exists } from './fs.js'
 import fs from 'fs/promises'
-import assert from 'node:assert'
+import { createOrgaBuildConfig, alias } from './plugin.js'
 
-const require = createRequire(import.meta.url)
+// Re-export alias for backwards compatibility
+export { alias }
 
-export const alias = {
-	react: path.dirname(require.resolve('react/package.json')),
-	'react-dom': path.dirname(require.resolve('react-dom/package.json')),
-	wouter: path.dirname(require.resolve('wouter'))
-}
+const ssrEntry = fileURLToPath(new URL('./ssr.jsx', import.meta.url))
+const clientEntry = fileURLToPath(new URL('./client.jsx', import.meta.url))
+const defaultIndexHtml = fileURLToPath(new URL('./index.html', import.meta.url))
 
 /**
  * @param {import('./config.js').Config} config
@@ -26,98 +21,89 @@ export async function build({
 	containerClass,
 	vitePlugins = []
 }) {
-	/* --- prepare folders, out, ssr, client --- */
 	await emptyDir(outDir)
 	const ssrOutDir = path.join(outDir, '.ssr')
 	const clientOutDir = path.join(outDir, '.client')
 
-	const plugins = [
-		setupOrga({ containerClass }),
-		react(),
-		pluginFactory({ dir: root }),
-		...vitePlugins
-	]
+	const { plugins, resolve } = createOrgaBuildConfig({
+		root,
+		outDir,
+		containerClass,
+		vitePlugins
+	})
 
-	/* --- build ssr bundle: server.mjs --- */
-	console.log('preparing ssr bundle...')
-	await viteBuild({
+	// Shared config with environment-specific build settings
+	const builder = await createBuilder({
 		root,
 		plugins,
-		build: {
-			ssr: true,
-			cssCodeSplit: false,
-			emptyOutDir: true,
-			rollupOptions: {
-				input: fileURLToPath(new URL('./ssr.jsx', import.meta.url)),
-				output: {
-					entryFileNames: '[name].mjs',
-					chunkFileNames: '[name]-[hash].mjs'
+		resolve,
+		ssr: { noExternal: true },
+		environments: {
+			ssr: {
+				build: {
+					ssr: true,
+					outDir: ssrOutDir,
+					cssCodeSplit: false,
+					emptyOutDir: true,
+					minify: false,
+					rollupOptions: {
+						input: ssrEntry,
+						output: {
+							entryFileNames: '[name].mjs',
+							chunkFileNames: '[name]-[hash].mjs'
+						}
+					}
 				}
 			},
-			outDir: ssrOutDir,
-			minify: false
-		},
-		ssr: {
-			noExternal: true
-		},
-		resolve: {
-			alias: alias
+			client: {
+				build: {
+					outDir: clientOutDir,
+					cssCodeSplit: false,
+					emptyOutDir: true,
+					assetsDir: 'assets',
+					rollupOptions: {
+						input: clientEntry,
+						preserveEntrySignatures: 'allow-extension'
+					}
+				}
+			}
 		}
 	})
 
-	/* --- import ssr bundle entry output, to get all the data and render function --- */
+	// Build SSR first to get render function and pages
+	console.log('preparing ssr bundle...')
+	await builder.build(builder.environments.ssr)
 
 	const { render, pages } = await import(
 		pathToFileURL(path.join(ssrOutDir, 'ssr.mjs')).toString()
 	)
 
-	/* --- build client bundle: client.mjs --- */
-	const _clientResult = await viteBuild({
-		root,
-		plugins,
-		build: {
-			cssCodeSplit: false,
-			emptyOutDir: true,
-			rollupOptions: {
-				input: fileURLToPath(new URL('./client.jsx', import.meta.url)),
-				preserveEntrySignatures: 'allow-extension'
-			},
-			assetsDir: 'assets',
-			outDir: clientOutDir
-		},
-		ssr: {
-			noExternal: true
-		},
-		resolve: {
-			alias: alias
-		}
-	})
+	// Build client bundle
+	const _clientResult = await builder.build(builder.environments.client)
 
-	/** @type {import('vite').Rollup.RollupOutput} */
-	let clientResult
-	if (Array.isArray(_clientResult)) {
-		if (_clientResult.length !== 1)
-			throw new Error(`expect viteBuild to have only one BuildResult`)
-		clientResult = _clientResult[0]
-	} else {
-		assert('output' in _clientResult)
-		clientResult = _clientResult
-	}
+	// Normalize build result to single RollupOutput
+	const clientOutput = Array.isArray(_clientResult)
+		? _clientResult[0].output
+		: 'output' in _clientResult
+			? _clientResult.output
+			: null
+	if (!clientOutput) throw new Error('Unexpected client build result')
 
 	/* --- get from client bundle result: entry chunk, css chunks --- */
-	const entryChunk = clientResult.output.filter((c) => {
-		return c.type === 'chunk' && c.isEntry
-	})[0]
+	const entryChunk = clientOutput.find(
+		(/** @type {any} */ c) => c.type === 'chunk' && c.isEntry
+	)
 
-	const cssChunks = clientResult.output.filter((c) => {
-		return c.type === 'asset' && c.fileName.endsWith('.css')
-	})
+	const cssChunks = clientOutput.filter(
+		(/** @type {any} */ c) => c.type === 'asset' && c.fileName.endsWith('.css')
+	)
 
 	/* --- get html template, inject entry js and css --- */
-	const template = await fs.readFile(
-		fileURLToPath(new URL('./index.html', import.meta.url)),
-		{ encoding: 'utf-8' }
-	)
+	// Check for user's index.html in project root, otherwise use default
+	const projectRoot = process.cwd()
+	const userIndexPath = path.join(projectRoot, 'index.html')
+	const indexHtmlPath = (await exists(userIndexPath)) ? userIndexPath : defaultIndexHtml
+	const template = await fs.readFile(indexHtmlPath, { encoding: 'utf-8' })
 	/* --- for each page path, render html using render function from ssr bundle, and inject the right css  --- */
 	const pagePaths = Object.keys(pages)
 	await Promise.all(
@@ -157,11 +143,11 @@ export async function build({
 		`
 		)
 		const css = cssChunks
-			.map((c) => `<link rel="stylesheet" href="/${c.fileName}">`)
+			.map((/** @type {any} */ c) => `<link rel="stylesheet" href="/${c.fileName}">`)
 			.join('\n')
 		html = html.replace(
 			'<script type="module" src="/@orga-build/main.js"></script>',
-			`<script type="module" src="/${entryChunk.fileName}"></script>`
+			`<script type="module" src="/${entryChunk?.fileName}"></script>`
 		)
 
 		html = html.replace('</head>', `${css}</head>`)

package/lib/config.d.ts

@@ -1,9 +1,8 @@
 /**
- * @param {string} cwd
  * @param {string[]} files
  * @returns {Promise<Config>}
  */
-export function loadConfig(cwd: string, ...files: string[]): Promise<Config>;
+export function loadConfig(...files: string[]): Promise<Config>;
 export type Config = {
     outDir: string;
     root: string;

package/lib/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["config.js"],"names":[],"mappings":"AAwBA;;;;GAIG;AACH,gCAJW,MAAM,YACN,MAAM,EAAE,GACN,OAAO,CAAC,MAAM,CAAC,CAkB3B;;YAvCa,MAAM;UACN,MAAM;cACN,MAAM,EAAE;eACR,MAAM,EAAE;;;;iBACR,OAAO,MAAM,EAAE,YAAY,EAAE;oBAC7B,MAAM,EAAE,GAAC,MAAM"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["config.js"],"names":[],"mappings":"AAuBA;;;GAGG;AACH,qCAHW,MAAM,EAAE,GACN,OAAO,CAAC,MAAM,CAAC,CAsC3B;;YA1Da,MAAM;UACN,MAAM;cACN,MAAM,EAAE;eACR,MAAM,EAAE;;;;iBACR,OAAO,MAAM,EAAE,YAAY,EAAE;oBAC7B,MAAM,EAAE,GAAC,MAAM"}

package/lib/config.js

@@ -1,6 +1,5 @@
 import fs from 'node:fs/promises'
 import path from 'node:path'
-import { resolvePath } from './fs.js'
 
 /**
  * @typedef {Object} Config
@@ -14,8 +13,8 @@ import { resolvePath } from './fs.js'
 
 /** @type {Config} */
 const defaultConfig = {
-	outDir: 'out',
-	root: 'pages',
+	outDir: '.out',
+	root: '.',
 	preBuild: [],
 	postBuild: [],
 	vitePlugins: [],
@@ -23,24 +22,43 @@ const defaultConfig = {
 }
 
 /**
- * @param {string} cwd
  * @param {string[]} files
  * @returns {Promise<Config>}
  */
-export async function loadConfig(cwd, ...files) {
+export async function loadConfig(...files) {
+	const cwd = process.cwd()
+
+	/**
+	 * @param {string} value
+	 */
+	const resolveConfigPath = (value) =>
+		path.isAbsolute(value) ? value : path.resolve(cwd, value)
+
+	let result = { ...defaultConfig }
+
 	for (const file of files) {
 		const filePath = path.join(cwd, file)
 
 		try {
 			await fs.access(filePath, fs.constants.F_OK)
-			const config = await import(filePath)
-			const result = { ...defaultConfig, ...config }
-			result.root = resolvePath(result.root)
-			result.outDir = resolvePath(result.outDir)
-			return result
+		} catch {
+			// File doesn't exist, try next
+			continue
+		}
+
+		try {
+			const module = await import(filePath)
+			// Support both default export (recommended) and named exports
+			const config = module.default || module
+			result = { ...defaultConfig, ...config }
+			break
 		} catch (err) {
-			console.error(err)
+			// Config file exists but has errors
+			console.error(`Error loading config from ${file}:`, err)
 		}
 	}
-	return defaultConfig
+
+	result.root = resolveConfigPath(result.root)
+	result.outDir = resolveConfigPath(result.outDir)
+	return result
 }

package/lib/files.d.ts

@@ -1,7 +1,11 @@
 /**
  * @param {string} dir
+ * @param {object} [options]
+ * @param {string} [options.outDir] - Output directory to exclude from file discovery
  */
-export function setup(dir: string): {
+export function setup(dir: string, { outDir }?: {
+    outDir?: string | undefined;
+}): {
     pages: () => Promise<Record<string, Page>>;
     page: (id: string) => Promise<Page>;
     components: () => Promise<string | null>;

package/lib/files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["files.js"],"names":[],"mappings":"AA8EA;;GAEG;AACH,2BAFW,MAAM;;eA2HJ,MAAM;;;;EAKlB;;cAxMa,MAAM;;;;YACN,MAAM;;;QAMN,MAAM;UACN,MAAM;UACN,MAAM;cACN,MAAM;SACN,KAAK,GAAG,KAAK,GAAG,KAAK;UACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC"}
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["files.js"],"names":[],"mappings":"AA8EA;;;;GAIG;AACH,2BAJW,MAAM,eAEd;IAAyB,MAAM;CACjC;;eAiIY,MAAM;;;;EAKlB;;cAjNa,MAAM;;;;YACN,MAAM;;;QAMN,MAAM;UACN,MAAM;UACN,MAAM;cACN,MAAM;SACN,KAAK,GAAG,KAAK,GAAG,KAAK;UACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC"}

package/lib/files.js

@@ -78,8 +78,17 @@ function getContentId(slug) {
 
 /**
  * @param {string} dir
+ * @param {object} [options]
+ * @param {string} [options.outDir] - Output directory to exclude from file discovery
  */
-export function setup(dir) {
+export function setup(dir, { outDir } = {}) {
+	const outDirRelative = outDir ? path.relative(dir, outDir) : null
+	// Only exclude outDir if it's inside the root (not an external path like ../out)
+	const outDirExclude =
+		outDirRelative && !outDirRelative.startsWith('..')
+			? `!${outDirRelative}/**`
+			: null
+
 	const pages = cache(async function () {
 		const files = await globby(
 			[
@@ -89,7 +98,7 @@ export function setup(dir) {
 				'!**/.*/**',
 				'!**/.*',
 				'!node_modules/**',
-				'!out/**'
+				...(outDirExclude ? [outDirExclude] : [])
 			],
 			{ cwd: dir }
 		)
@@ -113,7 +122,7 @@ export function setup(dir) {
 				'!**/.*/**',
 				'!**/.*',
 				'!node_modules/**',
-				'!out/**'
+				...(outDirExclude ? [outDirExclude] : [])
 			],
 			{
 				cwd: dir
@@ -137,7 +146,7 @@ export function setup(dir) {
 				'!**/.*/**',
 				'!**/.*',
 				'!node_modules/**',
-				'!out/**'
+				...(outDirExclude ? [outDirExclude] : [])
 			],
 			{
 				cwd: dir

package/lib/plugin.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @typedef {Object} OrgaBuildPluginOptions
+ * @property {string} root - Root directory for content files
+ * @property {string | undefined} [outDir] - Output directory (excluded from file discovery)
+ * @property {string|string[]} [containerClass] - CSS class(es) to wrap rendered content
+ */
+/**
+ * Creates the canonical orga-build plugin preset.
+ * This is the single composition path used by both dev and build.
+ *
+ * @param {OrgaBuildPluginOptions} options
+ * @returns {import('vite').PluginOption[]}
+ */
+export function orgaBuildPlugin({ root, outDir, containerClass }: OrgaBuildPluginOptions): import("vite").PluginOption[];
+/**
+ * Creates the full Vite config options for orga-build.
+ * Includes plugins, resolve aliases, and other shared config.
+ *
+ * @param {OrgaBuildPluginOptions & { outDir?: string, vitePlugins?: import('vite').PluginOption[], includeFallbackHtml?: boolean, projectRoot?: string }} options
+ * @returns {{ plugins: import('vite').PluginOption[], resolve: { alias: typeof alias } }}
+ */
+export function createOrgaBuildConfig({ root, outDir, containerClass, vitePlugins, includeFallbackHtml, projectRoot }: OrgaBuildPluginOptions & {
+    outDir?: string;
+    vitePlugins?: import("vite").PluginOption[];
+    includeFallbackHtml?: boolean;
+    projectRoot?: string;
+}): {
+    plugins: import("vite").PluginOption[];
+    resolve: {
+        alias: typeof alias;
+    };
+};
+/**
+ * Creates an HTML serving plugin that handles index.html for dev mode.
+ *
+ * This plugin:
+ * - Serves user's index.html from project root if present, otherwise uses the default template
+ * - Only handles GET/HEAD requests that accept HTML
+ * - Runs late (post middleware) so other plugins get first chance
+ * - Passes HTML through transformIndexHtml for ecosystem compatibility
+ * - Does not intercept asset requests
+ *
+ * @param {string} projectRoot - Project root directory (where orga.config.js lives)
+ * @returns {import('vite').Plugin}
+ */
+export function htmlFallbackPlugin(projectRoot: string): import("vite").Plugin;
+/**
+ * Alias map for React and wouter to ensure consistent resolution
+ */
+export const alias: {
+    react: string;
+    'react-dom': string;
+    wouter: string;
+};
+export type OrgaBuildPluginOptions = {
+    /**
+     * - Root directory for content files
+     */
+    root: string;
+    /**
+     * - Output directory (excluded from file discovery)
+     */
+    outDir?: string | undefined;
+    /**
+     * - CSS class(es) to wrap rendered content
+     */
+    containerClass?: string | string[];
+};
+//# sourceMappingURL=plugin.d.ts.map

package/lib/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["plugin.js"],"names":[],"mappings":"AAoBA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,kEAHW,sBAAsB,GACpB,OAAO,MAAM,EAAE,YAAY,EAAE,CAIzC;AAED;;;;;;GAMG;AACH,uHAHW,sBAAsB,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,MAAM,EAAE,YAAY,EAAE,CAAC;IAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5I;IAAE,OAAO,EAAE,OAAO,MAAM,EAAE,YAAY,EAAE,CAAC;IAAC,OAAO,EAAE;QAAE,KAAK,EAAE,OAAO,KAAK,CAAA;KAAE,CAAA;CAAE,CAoBxF;AAiBD;;;;;;;;;;;;GAYG;AACH,gDAHW,MAAM,GACJ,OAAO,MAAM,EAAE,MAAM,CA8CjC;AA9HD;;GAEG;AACH;;;;EAIC;;;;;UAIa,MAAM;;;;aACN,MAAM,GAAG,SAAS;;;;qBAClB,MAAM,GAAC,MAAM,EAAE"}

package/lib/plugin.js

@@ -0,0 +1,138 @@
+import path from 'node:path'
+import fs from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+import react from '@vitejs/plugin-react'
+import { setupOrga } from './orga.js'
+import { pluginFactory } from './vite.js'
+
+const require = createRequire(import.meta.url)
+const defaultIndexHtml = fileURLToPath(new URL('./index.html', import.meta.url))
+
+/**
+ * Alias map for React and wouter to ensure consistent resolution
+ */
+export const alias = {
+	react: path.dirname(require.resolve('react/package.json')),
+	'react-dom': path.dirname(require.resolve('react-dom/package.json')),
+	wouter: path.dirname(require.resolve('wouter'))
+}
+
+/**
+ * @typedef {Object} OrgaBuildPluginOptions
+ * @property {string} root - Root directory for content files
+ * @property {string | undefined} [outDir] - Output directory (excluded from file discovery)
+ * @property {string|string[]} [containerClass] - CSS class(es) to wrap rendered content
+ */
+
+/**
+ * Creates the canonical orga-build plugin preset.
+ * This is the single composition path used by both dev and build.
+ *
+ * @param {OrgaBuildPluginOptions} options
+ * @returns {import('vite').PluginOption[]}
+ */
+export function orgaBuildPlugin({ root, outDir, containerClass = [] }) {
+	return [setupOrga({ containerClass }), react(), pluginFactory({ dir: root, outDir })]
+}
+
+/**
+ * Creates the full Vite config options for orga-build.
+ * Includes plugins, resolve aliases, and other shared config.
+ *
+ * @param {OrgaBuildPluginOptions & { outDir?: string, vitePlugins?: import('vite').PluginOption[], includeFallbackHtml?: boolean, projectRoot?: string }} options
+ * @returns {{ plugins: import('vite').PluginOption[], resolve: { alias: typeof alias } }}
+ */
+export function createOrgaBuildConfig({
+	root,
+	outDir,
+	containerClass = [],
+	vitePlugins = [],
+	includeFallbackHtml = false,
+	projectRoot = process.cwd()
+}) {
+	const plugins = [...vitePlugins, ...orgaBuildPlugin({ root, outDir, containerClass })]
+	if (includeFallbackHtml) {
+		// HTML fallback must be first so it can handle HTML navigation requests
+		// before runtime plugins (e.g. Cloudflare) potentially return 404.
+		plugins.unshift(htmlFallbackPlugin(projectRoot))
+	}
+	return {
+		plugins,
+		resolve: { alias }
+	}
+}
+
+/**
+ * Checks if a user-provided index.html exists in the project root.
+ *
+ * @param {string} root - Project root directory
+ * @returns {Promise<boolean>}
+ */
+async function hasUserIndexHtml(root) {
+	try {
+		await fs.access(path.join(root, 'index.html'), fs.constants.F_OK)
+		return true
+	} catch {
+		return false
+	}
+}
+
+/**
+ * Creates an HTML serving plugin that handles index.html for dev mode.
+ *
+ * This plugin:
+ * - Serves user's index.html from project root if present, otherwise uses the default template
+ * - Only handles GET/HEAD requests that accept HTML
+ * - Runs late (post middleware) so other plugins get first chance
+ * - Passes HTML through transformIndexHtml for ecosystem compatibility
+ * - Does not intercept asset requests
+ *
+ * @param {string} projectRoot - Project root directory (where orga.config.js lives)
+ * @returns {import('vite').Plugin}
+ */
+export function htmlFallbackPlugin(projectRoot) {
+	return {
+		name: 'orga-build:html-fallback',
+
+		async configureServer(server) {
+			// Determine which index.html to use at startup
+			// Look for user's index.html in project root (where orga.config.js lives)
+			const userIndexPath = path.join(projectRoot, 'index.html')
+			const userHasIndex = await hasUserIndexHtml(projectRoot)
+			const indexHtmlPath = userHasIndex ? userIndexPath : defaultIndexHtml
+
+			// Add middleware to serve HTML early in the chain.
+			server.middlewares.use(async (req, res, next) => {
+				// Only handle GET/HEAD requests
+				if (req.method !== 'GET' && req.method !== 'HEAD') {
+					return next()
+				}
+
+				// Only handle browser-like navigation requests.
+				// Don't match generic */* accepts to avoid hijacking API requests.
+				const accept = req.headers.accept || ''
+				if (!accept.includes('text/html')) {
+					return next()
+				}
+
+				// Don't intercept asset requests (files with extensions)
+				const url = req.url || '/'
+				const pathname = url.split('?')[0]
+				if (pathname !== '/' && /\.\w+$/.test(pathname)) {
+					return next()
+				}
+
+				try {
+					let html = await fs.readFile(indexHtmlPath, 'utf-8')
+					html = await server.transformIndexHtml(url, html)
+					res.statusCode = 200
+					res.setHeader('Content-Type', 'text/html')
+					res.end(html)
+				} catch (e) {
+					next(e)
+				}
+			})
+		}
+	}
+}

package/lib/serve.d.ts

@@ -1,4 +1,6 @@
 /**
+ * Start the development server using native Vite.
+ *
  * @param {import('./config.js').Config} config
  * @param {number} [port]
  */

package/lib/serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["serve.js"],"names":[],"mappings":"AAQA;;;GAGG;AACH,8BAHW,OAAO,aAAa,EAAE,MAAM,SAC5B,MAAM,iBA6ChB"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["serve.js"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,8BAHW,OAAO,aAAa,EAAE,MAAM,SAC5B,MAAM,iBA2BhB"}

package/lib/serve.js

@@ -1,56 +1,36 @@
-import express from 'express'
+import path from 'node:path'
 import { createServer } from 'vite'
-import fs from 'node:fs/promises'
-import react from '@vitejs/plugin-react'
-import { pluginFactory } from './vite.js'
-import { alias } from './build.js'
-import { setupOrga } from './orga.js'
+import { createOrgaBuildConfig } from './plugin.js'
 
 /**
+ * Start the development server using native Vite.
+ *
  * @param {import('./config.js').Config} config
  * @param {number} [port]
  */
 export async function serve(config, port = 3000) {
-	const app = express()
-	const vite = await createServer({
-		plugins: [
-			setupOrga({ containerClass: config.containerClass }),
-			react(),
-			pluginFactory({ dir: config.root }),
-			...config.vitePlugins
-		],
-		server: { middlewareMode: true },
-		appType: 'custom',
-		resolve: {
-			alias: alias
-		}
-	})
-
-	app.use(vite.middlewares)
-	app.get('/favicon.ico', (req, res) => {
-		res.status(404).end()
+	const { plugins, resolve } = createOrgaBuildConfig({
+		root: config.root,
+		outDir: config.outDir,
+		containerClass: config.containerClass,
+		vitePlugins: config.vitePlugins,
+		includeFallbackHtml: true
 	})
 
-	app.use(async (req, res, next) => {
-		const url = req.originalUrl
-		if (req.method !== 'GET' || !req.headers.accept?.includes('text/html')) {
-			return next()
-		}
-
-		try {
-			// read index.html file from path relative to this file
-			const indexPath = new URL('./index.html', import.meta.url).pathname
-			let template = await fs.readFile(indexPath, { encoding: 'utf-8' })
-			template = await vite.transformIndexHtml(url, template)
-			const html = template
-			res.status(200).setHeader('Content-Type', 'text/html').end(html)
-		} catch (/** @type{any} */ e) {
-			vite.ssrFixStacktrace(e)
-			next(e)
+	const server = await createServer({
+		root: config.root,
+		plugins,
+		resolve,
+		appType: 'custom',
+		server: {
+			port,
+			strictPort: false,
+			watch: {
+				ignored: [path.resolve(config.outDir) + '/**']
+			}
 		}
 	})
 
-	app.listen(port, () => {
-		console.log(`  Server running at http://localhost:${port}/`)
-	})
+	await server.listen()
+	server.printUrls()
 }

package/lib/vite.d.ts

@@ -1,9 +1,11 @@
 /**
  * @param {Object} options
  * @param {string} options.dir
+ * @param {string} [options.outDir]
  * @returns {import('vite').Plugin}
  */
-export function pluginFactory({ dir }: {
+export function pluginFactory({ dir, outDir }: {
     dir: string;
+    outDir?: string | undefined;
 }): import("vite").Plugin;
 //# sourceMappingURL=vite.d.ts.map

package/lib/vite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["vite.js"],"names":[],"mappings":"AASA;;;;GAIG;AACH,uCAHG;IAAwB,GAAG,EAAnB,MAAM;CACd,GAAU,OAAO,MAAM,EAAE,MAAM,CA6JjC"}
+{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["vite.js"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,+CAJG;IAAwB,GAAG,EAAnB,MAAM;IACW,MAAM;CAC/B,GAAU,OAAO,MAAM,EAAE,MAAM,CA2JjC"}

package/lib/vite.js

@@ -10,15 +10,21 @@ const contentModuleIdResolved = '\0' + contentModuleId
 /**
  * @param {Object} options
  * @param {string} options.dir
+ * @param {string} [options.outDir]
  * @returns {import('vite').Plugin}
  */
-export function pluginFactory({ dir }) {
-	const files = setup(dir)
+export function pluginFactory({ dir, outDir }) {
+	const files = setup(dir, { outDir })
 
 	return {
 		name: 'vite-plugin-orga-pages',
 		enforce: 'pre',
 		config: (config, env) => ({
+			future: {
+				removePluginHookSsrArgument: 'warn',
+				removePluginHookHandleHotUpdate: 'warn',
+				removeSsrLoadModule: 'warn'
+			},
 			optimizeDeps: {
 				include: [
 					'react',
@@ -31,25 +37,18 @@ export function pluginFactory({ dir }) {
 			}
 		}),
 
-		configureServer(server) {
-			const { watcher, moduleGraph, ws } = server
-
-			// Invalidate content module on file changes
-			watcher.on('change', (filePath) => {
-				const module = moduleGraph.getModuleById(contentModuleIdResolved)
-				if (module) {
-					moduleGraph.invalidateModule(module)
-					// Send HMR update to client
-					ws.send({
-						type: 'full-reload',
-						path: '*'
-					})
-				}
-			})
+		hotUpdate() {
+			// Invalidate content module when content files change
+			const module = this.environment.moduleGraph.getModuleById(
+				contentModuleIdResolved
+			)
+			if (module) {
+				this.environment.moduleGraph.invalidateModule(module)
+				// Full reload for now; can optimize to HMR later
+				this.environment.hot.send({ type: 'full-reload', path: '*' })
+			}
 		},
 
-		buildStart() {},
-
 		async resolveId(id, importer) {
 			if (id === appEntryId) {
 				return appEntryId

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "orga-build",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "A simple tool that builds org-mode files into a website",
   "type": "module",
+  "engines": {
+    "node": ">=20.19.0"
+  },
   "bin": {
     "orga-build": "./cli.js"
   },
@@ -41,7 +44,6 @@
   },
   "dependencies": {
     "@vitejs/plugin-react": "^5.1.4",
-    "express": "^5.1.0",
     "globby": "^14.1.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -52,7 +54,6 @@
     "@orgajs/rollup": "1.3.3"
   },
   "devDependencies": {
-    "@types/express": "^5.0.1",
     "@types/hast": "^3.0.4",
     "@types/node": "^22.13.1",
     "@types/react": "^19.0.8",
@@ -60,6 +61,7 @@
     "orga": "4.6.0"
   },
   "scripts": {
-    "clean": "fd . -e d.ts -e d.ts.map -I -x rm {}"
+    "clean": "fd . -e d.ts -e d.ts.map -I -x rm {}",
+    "test": "node --test --no-warnings \"lib/__tests__/*.test.js\""
   }
 }