thunderous-server 0.0.0 → 0.0.2

package/README.md

@@ -1,7 +1,7 @@
 # Thunderous Server
 
 > [!CAUTION]
-> This project is experimental. It is not ready for production use at this time.
+> This project is experimental. It may not be suitable for production use at this time, as it is subject to bugs and breaking changes.
 
 **Thunderous Server is a web framework and static generator designed to support and supplement _plain old HTML_.**
 
@@ -119,6 +119,7 @@ Exported values are available in <script expr> tags.
 
 ## TODO
 
+- [ ] Add support for named slots in layouts
 - [ ] Create (or find existing) extension that supports:
   - [ ] TypeScript inside `<script>` tags
   - [ ] IDE navigation in `<script server>` and `<script expr>` tags (go to definition, find references, etc.)
@@ -127,3 +128,8 @@ Exported values are available in <script expr> tags.
   - [ ] Typechecking to ensure the default export in `<script server>` is `Record<PropertyKey, unknown>`
   - [ ] OPTIONAL: Lint and autofix for trailing `;` in `<script expr>` tags  
          _e.g., `('hello';)` is an invalid expression, so `<script expr>'hello';</script>` is technically incorrect. That said, Thunderous Server does handle this currently by stripping it from the content before it's evaluated._
+
+### Known Issues
+
+- [ ] The dev server is not reliably hot-reloading changes
+- [ ] The CSR views are not behaving as expected -- unclear if this is a bug in the server or the CSR package.

package/dist/index.cjs

@@ -31,7 +31,8 @@ var metaState = {
   config: {
     name: "",
     baseDir: "",
-    outDir: ""
+    outDir: "",
+    configDir: null
   },
   pathname: "/",
   breadcrumbs: [],

package/dist/index.d.cts

@@ -14,6 +14,10 @@ type ThunderousConfig = {
      * The output directory for builds.
      */
     outDir: string;
+    /**
+     * Non-configurable. The directory where the `thunderous.config.ts` file is located.
+     */
+    readonly configDir: string | null;
 };
 
 /**

package/dist/index.d.ts

@@ -14,6 +14,10 @@ type ThunderousConfig = {
      * The output directory for builds.
      */
     outDir: string;
+    /**
+     * Non-configurable. The directory where the `thunderous.config.ts` file is located.
+     */
+    readonly configDir: string | null;
 };
 
 /**

package/dist/index.js

@@ -3,7 +3,8 @@ var metaState = {
   config: {
     name: "",
     baseDir: "",
-    outDir: ""
+    outDir: "",
+    configDir: null
   },
   pathname: "/",
   breadcrumbs: [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thunderous-server",
-  "version": "0.0.0",
+  "version": "0.0.2",
   "description": "A simple server to enhance Thunderous components with SSR.",
   "license": "MIT",
   "author": "Jonathan DeWitt <jon.dewitt@thunder.solutions>",
@@ -30,9 +30,7 @@
     "@types/node": "^24.9.1",
     "@types/resolve": "^1.20.6",
     "@typescript-eslint/eslint-plugin": "^8.46.2",
-    "connect-livereload": "^0.6.1",
     "eslint": "^9.38.0",
-    "livereload": "^0.10.3",
     "prettier": "^3.6.2",
     "serve": "^14.2.5",
     "tsx": "^4.20.6",
@@ -41,13 +39,20 @@
     "undici-types": "^7.16.0"
   },
   "dependencies": {
+    "chalk": "^5.6.2",
+    "connect-livereload": "^0.6.1",
+    "emoji-space-shim": "^0.1.7",
     "es-module-lexer": "^1.7.0",
     "express": "^5.1.0",
+    "livereload": "^0.10.3",
+    "node-emoji": "^2.2.0",
+    "nodemon": "^3.1.14",
     "resolve": "^1.22.11",
-    "resolve.exports": "^2.0.3"
+    "resolve.exports": "^2.0.3",
+    "string-width": "^8.2.0"
   },
   "peerDependencies": {
-    "thunderous": ">=2.4.1"
+    "thunderous": ">=2.4.2"
   },
   "scripts": {
     "build": "tsup --no-clean",

package/src/cli.ts

@@ -1,13 +1,43 @@
 import { build } from './build';
-import { dev } from './dev';
+import nodemon from 'nodemon';
+import { readFileSync } from 'fs';
+import { config } from './config';
+import { relative, resolve } from 'path';
+import chalk from 'chalk';
 
 const args = process.argv.slice(2);
 
 if (args[0] === 'dev') {
 	try {
-		dev();
+		const ignoreFile = readFileSync('.gitignore', 'utf-8');
+		const ignores = ignoreFile.split('\n').filter((line) => line.trim() !== '' && !line.startsWith('#'));
+
+		// Set up nodemon for auto-restart on server changes
+		if (process.env.NODE_ENV !== 'production') {
+			nodemon({
+				script: resolve(`${import.meta.dirname}/dev.ts`),
+				ignore: ignores,
+				watch: [config.baseDir],
+				exec: 'tsx',
+			});
+
+			nodemon
+				.on('start', () => {
+					// console.log('App has started');
+				})
+				.on('quit', () => {
+					console.log(chalk.green('\nServer shut down successfully.\n'));
+					process.exit();
+				})
+				.on('restart', (files) => {
+					const filesList = (files ?? ['(none)']).map(
+						(file) => `  • ${chalk.cyan.underline(relative(config.configDir ?? process.cwd(), file))}\n`,
+					);
+					console.log('\nUpdates detected:\n', filesList.join(''));
+				});
+		}
 	} catch (error) {
-		console.error('Failed to start server:', error);
+		console.error('\x1b[31mFailed to start server:\x1b[0m', error);
 		process.exit(1);
 	}
 } else if (args[0] === 'build') {

package/src/config.ts

@@ -19,12 +19,17 @@ export type ThunderousConfig = {
 	 * The output directory for builds.
 	 */
 	outDir: string;
+	/**
+	 * Non-configurable. The directory where the `thunderous.config.ts` file is located.
+	 */
+	readonly configDir: string | null;
 };
 
 const DEFAULT_CONFIG = Object.freeze({
 	name: 'Thunderous Project',
 	baseDir: 'src',
 	outDir: 'dist',
+	configDir: null,
 });
 
 /** Find and import the `thunderous.config.ts` file. */
@@ -41,12 +46,13 @@ const resolveConfig = (): ThunderousConfig => {
 			configDir = currentDir;
 		}
 		if (rootDir !== undefined && configDir !== undefined) {
-			const configPath = join(configDir!, 'thunderous.config.ts');
+			const configPath = join(configDir, 'thunderous.config.ts');
 			const configOverrides: Partial<ThunderousConfig> = require(configPath);
 			return {
 				name: configOverrides.name ?? DEFAULT_CONFIG.name,
 				baseDir: configOverrides.baseDir?.replace(/^\/*/, '') ?? DEFAULT_CONFIG.baseDir,
 				outDir: configOverrides.outDir ?? DEFAULT_CONFIG.outDir,
+				configDir,
 			};
 		}
 		const parentDir = resolve(currentDir, '..');

package/src/dev.ts

@@ -1,7 +1,8 @@
 import express from 'express';
-import { readdirSync, statSync, mkdtempSync } from 'fs';
+import { existsSync, readdirSync, readFileSync, statSync, mkdtempSync } from 'fs';
 import { join, relative, resolve } from 'path';
 import { tmpdir } from 'os';
+import { ModuleKind, ScriptTarget, transpileModule, ImportsNotUsedAsValues } from 'typescript';
 import { bootstrapThunderous, generateStaticTemplate, generateImportMap, injectImportMap } from './generate';
 import { config } from './config';
 import livereload from 'livereload';
@@ -32,7 +33,7 @@ const bootstrapRoutes = (dir: string, app: express.Express, vendorDir: string) =
 
 				// Generate import map if there are client entry files
 				if (result.clientEntryFiles.length > 0) {
-					const importMapJson = generateImportMap(result.clientEntryFiles);
+					const importMapJson = generateImportMap(result.clientEntryFiles, vendorDir);
 					markup = injectImportMap(markup, importMapJson);
 				}
 
@@ -51,7 +52,7 @@ const bootstrapRoutes = (dir: string, app: express.Express, vendorDir: string) =
 export const dev = () => {
 	console.log('\n\x1b[36m\x1b[1m⚡⚡ Starting development server... ⚡⚡\x1b[0m\x1b[0m\n');
 
-	const PORT = process.env['PORT'] ?? 3000;
+	const PORT = process.env.PORT ?? 3000;
 
 	// Set up simple express server
 	const app = express();
@@ -81,6 +82,29 @@ export const dev = () => {
 	bootstrapThunderous();
 	bootstrapRoutes(`./${config.baseDir}`, app, vendorDir);
 
+	// Serve .js requests by transpiling the corresponding .ts source on-the-fly
+	app.use((req, res, next) => {
+		if (!req.path.endsWith('.js')) return next();
+		const tsPath = join(config.baseDir, req.path.replace(/\.js$/, '.ts'));
+		const tsxPath = join(config.baseDir, req.path.replace(/\.js$/, '.tsx'));
+		const srcPath = existsSync(tsPath) ? tsPath : existsSync(tsxPath) ? tsxPath : null;
+		if (srcPath === null) return next();
+		const source = readFileSync(srcPath, 'utf-8');
+		const { outputText } = transpileModule(source, {
+			compilerOptions: {
+				module: ModuleKind.ESNext,
+				target: ScriptTarget.ES2020,
+				sourceMap: false,
+				importsNotUsedAsValues: ImportsNotUsedAsValues.Remove,
+				verbatimModuleSyntax: true,
+				isolatedModules: true,
+			},
+			fileName: srcPath,
+			reportDiagnostics: false,
+		});
+		res.type('application/javascript').send(outputText);
+	});
+
 	// Serve static assets from the base directory
 	app.use(express.static(config.baseDir));
 
@@ -111,3 +135,6 @@ export const dev = () => {
 		});
 	});
 };
+
+// start directly, since this file is targeted directly by nodemon
+dev();

package/src/generate.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'fs';
 import { join, relative, resolve } from 'path';
 import { createRequire } from 'node:module';
 import { html } from 'thunderous';
@@ -17,6 +17,7 @@ const outRequire = createRequire(resolve(config.baseDir));
 // track state outside the function so that we only have to set one `onServerDefine` handler
 const renderState = {
 	markup: '',
+	insertedTags: new Set<string>(),
 };
 
 // ── Shared TypeScript compiler options (created once, reused everywhere) ──
@@ -43,6 +44,8 @@ export const bootstrapThunderous = () => {
 	const { insertTemplates, onServerDefine } = Thunderous;
 	// Update the markup each time a thunderous element is defined on the server
 	onServerDefine((tagName, innerHTML) => {
+		if (renderState.insertedTags.has(tagName)) return;
+		renderState.insertedTags.add(tagName);
 		renderState.markup = insertTemplates(
 			tagName,
 			innerHTML.replace(/\s+/gm, ' ').replace(/ >/g, '>'),
@@ -105,6 +108,13 @@ const extractTags = (markup: string) => {
 			continue;
 		}
 
+		// Skip HTML comments <!-- ... -->
+		if (markup.startsWith('<!--', i)) {
+			const commentEnd = markup.indexOf('-->', i + 4);
+			i = commentEnd === -1 ? markup.length : commentEnd + 3;
+			continue;
+		}
+
 		// <?layout href="…">
 		if (markup.startsWith('<?layout', i)) {
 			const close = markup.indexOf('>', i);
@@ -203,6 +213,7 @@ const extractTags = (markup: string) => {
  */
 export const generateStaticTemplate = (filePath: string) => {
 	renderState.markup = readFileSync(filePath, 'utf-8');
+	renderState.insertedTags.clear();
 
 	const name = basename(filePath, extname(filePath));
 
@@ -244,7 +255,8 @@ export const generateStaticTemplate = (filePath: string) => {
 	// ── Extract and apply layouts ──
 	const { layouts } = extractTags(renderState.markup);
 	for (let i = layouts.length - 1; i >= 0; i--) {
-		const l = layouts[i]!;
+		const l = layouts[i];
+		if (!l) continue;
 		renderState.markup = renderState.markup.slice(0, l.start) + renderState.markup.slice(l.end);
 	}
 	renderState.markup = renderState.markup.trim();
@@ -277,6 +289,8 @@ export const generateStaticTemplate = (filePath: string) => {
 	const scriptKey = (s: ParsedScript) => `${s.kind}|${s.href ?? ''}|${s.content}`;
 	const replacementMap = new Map<string, string>();
 
+	mkdirSync(resolvedOutDir, { recursive: true });
+
 	let scriptIndex = 0;
 	for (const script of scripts) {
 		const key = scriptKey(script);
@@ -309,14 +323,14 @@ export const generateStaticTemplate = (filePath: string) => {
 				delete outRequire.cache[outRequire.resolve(hrefAbsPath)];
 				module = outRequire(hrefAbsPath);
 			} else {
-				// inline: write temp .ts so outRequire can import it
-				const tsScriptFile = join(resolvedOutDir, `${name}-${scriptIndex}.tmp.ts`);
+				// inline: write temp .ts into baseDir so relative imports resolve correctly
+				const tsScriptFile = join(resolvedBaseDir, `${name}-${scriptIndex}.tmp.ts`);
 				writeFileSync(tsScriptFile, `// @ts-nocheck\n${content}`, 'utf-8');
 				tempFilesToCleanup.push(tsScriptFile);
 				delete outRequire.cache[outRequire.resolve(tsScriptFile)];
 				module = outRequire(tsScriptFile);
 			}
-			const values = module['default'] ?? {};
+			const values = module.default ?? {};
 			for (const k in values) {
 				const val = (values as Record<string, unknown>)[k];
 				safeValues[k] = typeof val === 'string' ? escapeHtml(val) : val;
@@ -340,11 +354,14 @@ export const generateStaticTemplate = (filePath: string) => {
 			const js = transpileTs(`// @ts-nocheck\n${content}`, `${name}-${scriptIndex}.ts`);
 			const fixedJs = js
 				.replace(/(import\s+.+?\s+from\s+['"](?:\.\.?\/|\/)[^'"]+?)\.tsx?(['"])/gm, '$1.js$2')
-				.replace(/(import\s+.+?\s+from\s+['"](?:\.\.?\/|\/)[^'"]+?)(?<!\.m?js)(['"])/gm, '$1.js$2');
+				.replace(/(import\s+.+?\s+from\s+['"](?:\.\.?\/|\/)[^'"]+?)(?<!\.m?js)(['"])/gm, '$1.js$2')
+				// Convert relative ./ imports to absolute / so they resolve correctly
+				// regardless of the page's URL depth (e.g. /about/contact)
+				.replace(/(import\s+.+?\s+from\s+['"])\.\//gm, '$1/');
 			replacementMap.set(key, `<script type="module">\n${fixedJs}\n</script>`);
 
-			// Write .js to outDir for vendorization
-			const jsOutPath = join(resolvedOutDir, `${name}-${scriptIndex}.tmp.js`);
+			// Write .js to baseDir for vendorization (so relative imports resolve from source tree)
+			const jsOutPath = join(resolvedBaseDir, `${name}-${scriptIndex}.tmp.js`);
 			writeFileSync(jsOutPath, js, 'utf-8');
 			tempFilesToCleanup.push(jsOutPath);
 			clientEntryFiles.push(resolve(jsOutPath));
@@ -356,7 +373,8 @@ export const generateStaticTemplate = (filePath: string) => {
 	// ── Re-parse and apply all replacements in one reverse pass ──
 	const { scripts: freshScripts } = extractTags(renderState.markup);
 	for (let i = freshScripts.length - 1; i >= 0; i--) {
-		const script = freshScripts[i]!;
+		const script = freshScripts[i];
+		if (!script) continue;
 		const key = scriptKey(script);
 		const replacement = replacementMap.get(key);
 		if (replacement === undefined) continue;
@@ -403,16 +421,17 @@ export const generateStaticTemplate = (filePath: string) => {
  * Generate import maps from entry files using vendorization.
  * Returns the import map JSON string that can be injected into HTML.
  */
-export const generateImportMap = (entryFiles: string[]): string => {
+export const generateImportMap = (entryFiles: string[], outputDir?: string): string => {
+	const outDir = outputDir ?? config.outDir;
 	if (entryFiles.length === 0) {
 		return JSON.stringify({ imports: {} }, null, 2);
 	}
 
 	console.log(`\x1b[90mVendorizing dependencies from ${entryFiles.length} entry file(s)...\x1b[0m`);
-	processNodeModules(entryFiles, config.outDir);
+	processNodeModules(entryFiles, outDir);
 	console.log(`\x1b[32m✓ Import map generated\x1b[0m`);
 
-	const importMapPath = join(config.outDir, 'importmap.json');
+	const importMapPath = join(outDir, 'importmap.json');
 	if (existsSync(importMapPath)) {
 		return readFileSync(importMapPath, 'utf-8');
 	}
@@ -423,27 +442,41 @@ export const generateImportMap = (entryFiles: string[]): string => {
 /**
  * Inject an import map into HTML content.
  * If an import map script already exists, it will be replaced.
- * Otherwise, it will be injected before the first script tag or at the end.
+ * Otherwise, it will be injected into the <head> so it's in a consistent
+ * position across all pages (important for CSR partial-update validation).
  */
 export const injectImportMap = (html: string, importMapJson: string): string => {
-	const importMapTag = `<script type="importmap">\n${importMapJson}\n</script>`;
-
-	// Check if there's already an import map and replace it
-	const existingImportMapRegex = /<script\s+type="importmap"[^>]*>[\s\S]*?<\/script>/i;
-	if (existingImportMapRegex.test(html)) {
-		return html.replace(existingImportMapRegex, importMapTag);
-	}
+	const scriptId = `IMPORTMAP_${crypto.randomUUID()}`;
+	const importMapTag = `<script type="importmap" id="${scriptId}">\n${importMapJson}\n</script>`;
 
-	// Otherwise inject before first script tag
-	const firstScriptMatch = /<script/i.exec(html);
-	if (firstScriptMatch?.index !== undefined) {
-		return html.slice(0, firstScriptMatch.index) + importMapTag + '\n' + html.slice(firstScriptMatch.index);
+	// Check if we've already injected an import map (by our ID pattern) and replace it
+	const ownImportMapRegex = /<script\s+type="importmap"\s+id="IMPORTMAP_[^"]*"[^>]*>[\s\S]*?<\/script>/i;
+	if (ownImportMapRegex.test(html)) {
+		return html.replace(ownImportMapRegex, importMapTag);
 	}
 
-	// No script tag found, inject before </head> if possible
+	// Inject before </head> so the import map is always in a consistent position
 	const headCloseMatch = /<\/head>/i.exec(html);
 	if (headCloseMatch?.index !== undefined) {
-		return html.slice(0, headCloseMatch.index) + importMapTag + '\n' + html.slice(headCloseMatch.index);
+		return html.slice(0, headCloseMatch.index) + '\t' + importMapTag + '\n' + html.slice(headCloseMatch.index);
+	}
+
+	// Fallback: inject before first script tag (skip HTML comments)
+	let searchPos = 0;
+	while (searchPos < html.length) {
+		// Skip HTML comments
+		const commentStart = html.indexOf('<!--', searchPos);
+		const scriptMatch = /<script/i.exec(html.slice(searchPos));
+		if (scriptMatch === null) break;
+		const scriptPos = searchPos + scriptMatch.index;
+		// If a comment starts before this <script, skip past the comment
+		if (commentStart !== -1 && commentStart < scriptPos) {
+			const commentEnd = html.indexOf('-->', commentStart + 4);
+			searchPos = commentEnd === -1 ? html.length : commentEnd + 3;
+			continue;
+		}
+		// Found a real <script outside of a comment
+		return html.slice(0, scriptPos) + importMapTag + '\n' + html.slice(scriptPos);
 	}
 
 	// Last resort: add at the end

package/src/meta.ts

@@ -56,6 +56,7 @@ const metaState: Meta = {
 		name: '',
 		baseDir: '',
 		outDir: '',
+		configDir: null,
 	},
 	pathname: '/',
 	breadcrumbs: [],

package/src/vendorize.ts

@@ -1,4 +1,4 @@
-import { accessSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { accessSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path, { dirname, relative, join } from 'node:path';
 import resolve from 'resolve';
 import { resolve as resolveExports } from 'resolve.exports';
@@ -31,7 +31,21 @@ export function processNodeModules(entryFiles: string[], outputDir?: string) {
 		if (seen.has(file)) continue;
 		seen.add(file);
 
-		const code = readFileSync(file, 'utf8');
+		// In dev mode, .js may not exist yet; fall back to .ts source and transpile
+		let code: string;
+		if (existsSync(file)) {
+			code = readFileSync(file, 'utf8');
+		} else {
+			const tsFile = file.replace(/\.js$/, '.ts');
+			const tsxFile = file.replace(/\.js$/, '.tsx');
+			if (existsSync(tsFile)) {
+				code = transpileTsFast(readFileSync(tsFile, 'utf8'), tsFile);
+			} else if (existsSync(tsxFile)) {
+				code = transpileTsFast(readFileSync(tsxFile, 'utf8'), tsxFile);
+			} else {
+				throw new Error(`Cannot find module: ${file} (also tried .ts/.tsx)`);
+			}
+		}
 		const [imports] = parse(code);
 
 		for (const im of imports) {
@@ -49,12 +63,12 @@ export function processNodeModules(entryFiles: string[], outputDir?: string) {
 						// Prefer declared export for browser/import
 						const sub = resolveExports(pkg, '.', { conditions: CONDITIONS });
 						if (sub) {
-							pkg['main'] = sub;
+							pkg.main = sub;
 							return pkg;
 						}
 						// If no exports field, prefer "module" over "main" for ESM
-						if (pkg['module']) {
-							pkg['main'] = pkg['module'];
+						if (pkg.module) {
+							pkg.main = pkg.module;
 						}
 						// Otherwise fall back to pkg.main (default behavior)
 						return pkg;
@@ -84,7 +98,9 @@ export function processNodeModules(entryFiles: string[], outputDir?: string) {
 
 function withJsOrTs(p: string) {
 	const cand = [p, p + '.mjs', p + '.js', p + '.ts', p + '.tsx'];
-	for (const c of cand) return c; // optimistic; upstream readFile will fail fast if wrong
+	for (const c of cand) {
+		if (existsSync(c)) return c;
+	}
 	return p;
 }
 
@@ -92,7 +108,7 @@ function vendorizeFile(absPath: string, vendorRoot: string) {
 	// Find package root & metadata
 	const pkgRoot = findPkgRoot(absPath);
 	const pkg = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8')) as Record<string, string>;
-	const versionTag = `${pkg['name']!.replace('/', '__')}@${pkg['version']!}`;
+	const versionTag = `${pkg.name?.replace('/', '__') ?? 'unknown'}@${pkg.version ?? '0.0.0'}`;
 	const relFromPkg = relative(pkgRoot, absPath);
 	const outDir = join(vendorRoot, versionTag);
 	const outPath = join(outDir, relFromPkg.replace(/\.(ts|tsx)$/, '.js'));