npm - thunderous-server - Versions diffs - 0.0.0 - Mend

thunderous-server 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Jonathan DeWitt
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,129 @@
+# Thunderous Server
+> [!CAUTION]
+> This project is experimental. It is not ready for production use at this time.
+**Thunderous Server is a web framework and static generator designed to support and supplement _plain old HTML_.**
+**What it does NOT do:**
+- No special file extensions
+- No unusual mixed syntax
+- No complex route config
+- No compiler magic
+**What it DOES:**
+- HTML is enhanced to support server-side templating and layout composition.
+- TypeScript is compiled for browser runtimes
+- NPM dependencies are extracted to static assets and referenced via import maps
+All you need to set up your app is a source folder (`src` by default) with an `index.html` file. Routing is achieved natively, through the folder structure
+## Examples
+**\_layout.html**:
+```html
+<!--
+Since this file begins with an underscore, it will not be included
+in the static output. Its contents may be used by other HTML files
+that reference it, but it will never be served directly.
+-->
+<html>
+  <head>
+    <title>Thunderous Server</title>
+  </head>
+  <body>
+    <!--
+    <slot> tags are usually reserved for shadow DOM, but they are
+    appropriate here since they serve a similar purpose. Any HTML
+    file that includes this layout will insert its content into this
+    slot.
+    -->
+    <slot></slot>
+  </body>
+</html>
+```
+**index.html**:
+```html
+<!--
+This is a "processing instruction", and there's already support
+in XML and the DOM spec. Browsers just parse them as comments,
+but Thunderous Server will strip this away before it reaches
+the browser anyway.
+-->
+<?layout href="_layout.html">
+<ul>
+  <!--
+  This is evaluated in-place and replaced with the result.
+  This is server-side only; you'll never see <script expr>
+  in the source markup served to the browser.
+  -->
+  <script expr>
+    list.map((item) => html` <li>test ${label} - ${item}</li> `);
+  </script>
+</ul>
+<!--
+Thunderous supports SSR web components by rendering declarative
+shadow DOM in the source markup sent to the browser. When
+MyComponent.define() is called on the server, it will inject
+this element with <my-component>'s rendered output.
+-->
+<my-component></my-component>
+<!--
+This is ordinary client-only code that remains in the source markup
+sent to the browser.
+-->
+<script>
+  console.log('Hello from the browser!');
+</script>
+<!--
+This is also client-only. Client-side modules are processed to
+"vendorize" NPM dependencies. That is, imports are ejected as
+assets the browser can see and use. This does NOT bundle; instead,
+it generates an import map. It will only vendorize the dependencies
+that are actually imported.
+-->
+<script type="module">
+  console.log('Hello from a module!');
+</script>
+<!--
+This runs on both the client and server. Isomorphic scripts are
+always type="module". Since it runs on the client, it will also
+vendorize NPM dependencies.
+-->
+<script isomorphic>
+  import { MyComponent } from './scripts';
+  MyComponent.define('my-component');
+</script>
+<!--
+This runs on the server only. Server scripts are always modules.
+Exported values are available in <script expr> tags.
+-->
+<script server>
+  export default {
+    label: 'Item',
+    list: [1, 2, 3, 4, 5],
+  };
+</script>
+```
+## TODO
+- [ ] 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.)
+  - [ ] Auto-imports for `<script server>`, `<script isomorphic>`, and `<script type="module">`
+  - [ ] Lint against multiple `<script server>` tags to avoid export collisions
+  - [ ] 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._

package/bin/thunderous ADDED Viewed

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// Register tsx loaders in-process (no child process spawn needed)
+import { register as registerEsm } from 'tsx/esm/api';
+import { register as registerCjs } from 'tsx/cjs/api';
+registerCjs();
+registerEsm();
+// Dynamically import the TypeScript CLI entry point
+await import('../src/cli.ts');

package/dist/index.cjs ADDED Viewed

@@ -0,0 +1,69 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  escapeHtml: () => escapeHtml,
+  getMeta: () => getMeta,
+  raw: () => raw
+});
+module.exports = __toCommonJS(index_exports);
+// src/meta.ts
+var metaState = {
+  config: {
+    name: "",
+    baseDir: "",
+    outDir: ""
+  },
+  pathname: "/",
+  breadcrumbs: [],
+  title: "",
+  name: "",
+  filename: ""
+};
+var getMeta = () => {
+  return Object.freeze({
+    ...metaState,
+    config: { ...metaState.config },
+    breadcrumbs: [...metaState.breadcrumbs]
+  });
+};
+// src/utilities.ts
+var escapeHtml = (str) => {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+};
+var RawHtml = class {
+  value;
+  constructor(value) {
+    this.value = value;
+  }
+  toString() {
+    return this.value;
+  }
+};
+var raw = (str) => new RawHtml(str);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  escapeHtml,
+  getMeta,
+  raw
+});

package/dist/index.d.cts ADDED Viewed

@@ -0,0 +1,85 @@
+/**
+ * The type for the default export from `thunderous.config.ts`.
+ */
+type ThunderousConfig = {
+    /**
+     * The name of the site.
+     */
+    name: string;
+    /**
+     * The base directory where HTML files and static assets are served.
+     */
+    baseDir: string;
+    /**
+     * The output directory for builds.
+     */
+    outDir: string;
+};
+/**
+ * A breadcrumb (name and path) for a given page.
+ */
+type Breadcrumb = {
+    /**
+     * The name of the page.
+     */
+    name: string;
+    /**
+     * The full URL path to the page.
+     */
+    pathname: string;
+};
+/**
+ * Metadata about the current page being rendered.
+ */
+type Meta = {
+    /**
+     * The configuration object from `thunderous.config.ts`.
+     */
+    config: ThunderousConfig;
+    /**
+     * The pathname of the current page being rendered.
+     */
+    pathname: string;
+    /**
+     * The breadcrumbs of the current page being rendered.
+     */
+    breadcrumbs: Breadcrumb[];
+    /**
+     * The inferred title of the current page being rendered.
+     *
+     * This is derived from the filename, replacing hyphens and underscores
+     * with spaces, and capitalizing the first letter of each word.
+     */
+    title: string;
+    /**
+     * The name of the current page being rendered.
+     *
+     * This is the filename without the extension.
+     */
+    name: string;
+    /**
+     * The filename of the current page being rendered.
+     *
+     * This is the full filename including the extension.
+     */
+    filename: string;
+};
+/** Get metadata about the current page being rendered. */
+declare const getMeta: () => Meta;
+/**
+ * Escape a string for safe insertion into HTML.
+ */
+declare const escapeHtml: (str: string) => string;
+declare class RawHtml {
+    value: string;
+    constructor(value: string);
+    toString(): string;
+}
+/**
+ * Wrap a string so it bypasses automatic HTML escaping in `<script expr>`.
+ */
+declare const raw: (str: string) => RawHtml;
+export { escapeHtml, getMeta, raw };

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,85 @@
+/**
+ * The type for the default export from `thunderous.config.ts`.
+ */
+type ThunderousConfig = {
+    /**
+     * The name of the site.
+     */
+    name: string;
+    /**
+     * The base directory where HTML files and static assets are served.
+     */
+    baseDir: string;
+    /**
+     * The output directory for builds.
+     */
+    outDir: string;
+};
+/**
+ * A breadcrumb (name and path) for a given page.
+ */
+type Breadcrumb = {
+    /**
+     * The name of the page.
+     */
+    name: string;
+    /**
+     * The full URL path to the page.
+     */
+    pathname: string;
+};
+/**
+ * Metadata about the current page being rendered.
+ */
+type Meta = {
+    /**
+     * The configuration object from `thunderous.config.ts`.
+     */
+    config: ThunderousConfig;
+    /**
+     * The pathname of the current page being rendered.
+     */
+    pathname: string;
+    /**
+     * The breadcrumbs of the current page being rendered.
+     */
+    breadcrumbs: Breadcrumb[];
+    /**
+     * The inferred title of the current page being rendered.
+     *
+     * This is derived from the filename, replacing hyphens and underscores
+     * with spaces, and capitalizing the first letter of each word.
+     */
+    title: string;
+    /**
+     * The name of the current page being rendered.
+     *
+     * This is the filename without the extension.
+     */
+    name: string;
+    /**
+     * The filename of the current page being rendered.
+     *
+     * This is the full filename including the extension.
+     */
+    filename: string;
+};
+/** Get metadata about the current page being rendered. */
+declare const getMeta: () => Meta;
+/**
+ * Escape a string for safe insertion into HTML.
+ */
+declare const escapeHtml: (str: string) => string;
+declare class RawHtml {
+    value: string;
+    constructor(value: string);
+    toString(): string;
+}
+/**
+ * Wrap a string so it bypasses automatic HTML escaping in `<script expr>`.
+ */
+declare const raw: (str: string) => RawHtml;
+export { escapeHtml, getMeta, raw };

package/dist/index.js ADDED Viewed

@@ -0,0 +1,40 @@
+// src/meta.ts
+var metaState = {
+  config: {
+    name: "",
+    baseDir: "",
+    outDir: ""
+  },
+  pathname: "/",
+  breadcrumbs: [],
+  title: "",
+  name: "",
+  filename: ""
+};
+var getMeta = () => {
+  return Object.freeze({
+    ...metaState,
+    config: { ...metaState.config },
+    breadcrumbs: [...metaState.breadcrumbs]
+  });
+};
+// src/utilities.ts
+var escapeHtml = (str) => {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+};
+var RawHtml = class {
+  value;
+  constructor(value) {
+    this.value = value;
+  }
+  toString() {
+    return this.value;
+  }
+};
+var raw = (str) => new RawHtml(str);
+export {
+  escapeHtml,
+  getMeta,
+  raw
+};

package/package.json ADDED Viewed

@@ -0,0 +1,63 @@
+{
+  "name": "thunderous-server",
+  "version": "0.0.0",
+  "description": "A simple server to enhance Thunderous components with SSR.",
+  "license": "MIT",
+  "author": "Jonathan DeWitt <jon.dewitt@thunder.solutions>",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "thunderous": "./bin/thunderous"
+  },
+  "files": [
+    "/dist",
+    "/bin",
+    "/src",
+    "/types",
+    "/package.json",
+    "/README.md"
+  ],
+  "devDependencies": {
+    "@eslint/css": "^0.13.0",
+    "@eslint/js": "^9.38.0",
+    "@eslint/json": "^0.13.2",
+    "@total-typescript/ts-reset": "^0.6.1",
+    "@types/connect-livereload": "^0.6.3",
+    "@types/express": "^5.0.3",
+    "@types/livereload": "^0.9.5",
+    "@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",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.2",
+    "undici-types": "^7.16.0"
+  },
+  "dependencies": {
+    "es-module-lexer": "^1.7.0",
+    "express": "^5.1.0",
+    "resolve": "^1.22.11",
+    "resolve.exports": "^2.0.3"
+  },
+  "peerDependencies": {
+    "thunderous": ">=2.4.1"
+  },
+  "scripts": {
+    "build": "tsup --no-clean",
+    "demo": "cd demo && npm run",
+    "demo:install": "cd demo && npm install",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --check . --ignore-path ../../.gitignore",
+    "format:fix": "prettier --write . --ignore-path ../../.gitignore",
+    "typecheck": "tsc --noEmit",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}

package/src/build.ts ADDED Viewed

@@ -0,0 +1,134 @@
+import { cpSync, existsSync, rmSync, writeFileSync, readFileSync, mkdirSync } from 'fs';
+import { join, resolve, dirname, relative } from 'path';
+import {
+	bootstrapThunderous,
+	processFiles,
+	generateStaticTemplate,
+	transpileTsFile,
+	generateImportMap,
+	injectImportMap,
+} from './generate';
+import { config } from './config';
+/** Make the directory if it does not exist. Not worth installing fs-extra just for this. */
+export const ensureDirSync = (dirPath: string) => {
+	if (!existsSync(dirPath)) {
+		mkdirSync(dirPath, { recursive: true });
+	}
+};
+/**
+ * Build the static site.
+ */
+export const build = () => {
+	console.log('\x1b[36m🔨 Building static site...\x1b[0m\n');
+	const baseDir = resolve(config.baseDir);
+	const outDir = resolve(config.outDir);
+	if (!existsSync(baseDir)) {
+		console.error(`\x1b[31mError: Base directory "${baseDir}" does not exist.\x1b[0m`);
+		process.exit(1);
+	}
+	// Clean and create output directory
+	if (existsSync(outDir)) {
+		rmSync(outDir, { recursive: true });
+	}
+	ensureDirSync(outDir);
+	// Copy all files (excluding build files which we'll process separately)
+	console.log(`\x1b[90mCopying static assets...\x1b[0m`);
+	cpSync(baseDir, outDir, {
+		recursive: true,
+		filter: (src) => !/\.server\.(ts|js)$/.test(src),
+	});
+	bootstrapThunderous();
+	// Transpile TypeScript files FIRST and collect entry points
+	console.log(`\x1b[90mTranspiling TypeScript files...\x1b[0m`);
+	const entryFiles: string[] = [];
+	processFiles({
+		dir: outDir,
+		filter: (filePath) => /(?<!\.d|\.tmp|\.server)\.ts$/.test(filePath),
+		callback: (filePath) => {
+			const relPath = relative(outDir, filePath);
+			console.log(`\x1b[90mTranspiling: ${relPath}\x1b[0m`);
+			try {
+				const jsPath = transpileTsFile(filePath);
+				entryFiles.push(jsPath);
+				console.log(`\x1b[32m✓ Transpiled: ${relPath} → ${relative(outDir, jsPath)}\x1b[0m`);
+			} catch (error) {
+				console.error(`\x1b[31m✗ Error transpiling ${filePath}:\x1b[0m`, error);
+			}
+		},
+	});
+	// Process HTML files AFTER transpilation
+	console.log(`\x1b[90mProcessing HTML files...\x1b[0m`);
+	const htmlEntryFiles: string[] = [];
+	const cleanupFunctions: Array<() => void> = [];
+	const errors: string[] = [];
+	processFiles({
+		dir: baseDir,
+		filter: (filePath) => filePath.endsWith('.html') && !filePath.split('/').pop()!.startsWith('_'),
+		callback: (filePath) => {
+			console.log(`\x1b[90mProcessing: ${relative(baseDir, filePath)}\x1b[0m`);
+			try {
+				const result = generateStaticTemplate(filePath);
+				const markup = result.markup;
+				// Collect client entry files from this HTML
+				htmlEntryFiles.push(...result.clientEntryFiles);
+				cleanupFunctions.push(result.cleanup);
+				// Calculate the output path
+				const relativePath = relative(baseDir, filePath);
+				const outputPath = join(outDir, relativePath);
+				// Ensure output directory exists
+				ensureDirSync(dirname(outputPath));
+				// Write the processed HTML
+				writeFileSync(outputPath, markup, 'utf-8');
+				console.log(`\x1b[32m✓ Generated: ${relativePath}\x1b[0m`);
+			} catch (error) {
+				console.error(`\x1b[31m✗ Error processing ${filePath}:\x1b[0m`, error);
+				errors.push(filePath);
+			}
+		},
+	});
+	// Vendorize node modules based on collected entry files
+	const allEntryFiles = [...htmlEntryFiles, ...entryFiles];
+	if (allEntryFiles.length > 0) {
+		const importMapJson = generateImportMap(allEntryFiles);
+		// Inject import map into HTML files
+		processFiles({
+			dir: outDir,
+			filter: (filePath) => filePath.endsWith('.html'),
+			callback: (filePath) => {
+				let html = readFileSync(filePath, 'utf-8');
+				html = injectImportMap(html, importMapJson);
+				writeFileSync(filePath, html, 'utf-8');
+			},
+		});
+		console.log(`\x1b[32m✓ Import map injected into HTML files\x1b[0m`);
+	}
+	// Clean up temporary files from HTML processing
+	for (const cleanup of cleanupFunctions) {
+		cleanup();
+	}
+	if (errors.length > 0) {
+		console.error(`\n\x1b[31m❌ Build failed with ${errors.length} error(s).\x1b[0m`);
+		process.exit(1);
+	}
+	console.log(`\n\x1b[32m✅ Static site built successfully in "${outDir}"\x1b[0m`);
+};

package/src/cli.ts ADDED Viewed

@@ -0,0 +1,24 @@
+import { build } from './build';
+import { dev } from './dev';
+const args = process.argv.slice(2);
+if (args[0] === 'dev') {
+	try {
+		dev();
+	} catch (error) {
+		console.error('Failed to start server:', error);
+		process.exit(1);
+	}
+} else if (args[0] === 'build') {
+	try {
+		build();
+	} catch (error) {
+		console.error('\x1b[31mBuild failed:\x1b[0m', error);
+		process.exit(1);
+	}
+} else {
+	console.log('Usage:');
+	console.log('  --dev    Start the development server');
+	console.log('  --build  Build the static site');
+}