@knighted/jsx 1.2.0-rc.0 → 1.2.0-rc.1

package/README.md

@@ -4,7 +4,23 @@
 [![codecov](https://codecov.io/gh/knightedcodemonkey/jsx/graph/badge.svg?token=tjxuFwcwkr)](https://codecov.io/gh/knightedcodemonkey/jsx)
 [![NPM version](https://img.shields.io/npm/v/@knighted/jsx.svg)](https://www.npmjs.com/package/@knighted/jsx)
 
-A runtime JSX template tag backed by the [`oxc-parser`](https://github.com/oxc-project/oxc) WebAssembly build. Use real JSX syntax directly inside template literals and turn the result into live DOM nodes (or values returned from your own components) without running a bundler.
+A runtime JSX template tag backed by the [`oxc-parser`](https://github.com/oxc-project/oxc) WebAssembly build. Use real JSX syntax directly inside template literals and turn the result into live DOM nodes (or values returned from your own components) without running a bundler. One syntax works everywhere—browser scripts, SSR utilities, and bundler pipelines—no separate transpilation step required.
+
+## Key features
+
+- **Parse true JSX with no build step** – template literals go through `oxc-parser`, so fragments, spreads, and SVG namespaces all work as expected.
+- **DOM + React runtimes** – choose `jsx` for DOM nodes or `reactJsx` for React elements, and mix them freely (even on the server).
+- **Loader + SSR support** – ship tagged templates through Webpack/Rspack, Next.js, or plain Node by using the loader and the `@knighted/jsx/node` entry.
+
+## Quick links
+
+- [Usage](#usage)
+- [React runtime](#react-runtime-reactjsx)
+- [Loader integration](#loader-integration)
+- [Node / SSR usage](#node--ssr-usage)
+- [Next.js integration](#nextjs-integration)
+- [Browser usage](#browser-usage)
+- [Testing & demos](#testing)
 
 ## Installation
 
@@ -32,8 +48,11 @@ npm_config_ignore_platform=true npm install @oxc-parser/binding-wasm32-wasi
 ```ts
 import { jsx } from '@knighted/jsx'
 
-const count = 3
-const handleClick = () => console.log('clicked!')
+let count = 3
+const handleClick = () => {
+  count += 1
+  console.log(`Count is now ${count}`)
+}
 
 const button = jsx`
   <button className={${`counter-${count}`}} onClick={${handleClick}}>
@@ -49,17 +68,25 @@ document.body.append(button)
 Need to compose React elements instead of DOM nodes? Import the dedicated helper from the `@knighted/jsx/react` subpath (React 18+ and `react-dom` are still required to mount the tree):
 
 ```ts
+import { useState } from 'react'
 import { reactJsx } from '@knighted/jsx/react'
 import { createRoot } from 'react-dom/client'
 
-const view = reactJsx`
-  <section className="react-demo">
-    <h2>Hello from React</h2>
-    <button onClick={${() => console.log('clicked!')}}>Tap me</button>
-  </section>
-`
+const App = () => {
+  const [count, setCount] = useState(0)
+
+  return reactJsx`
+    <section className="react-demo">
+      <h2>Hello from React</h2>
+      <p>Count is {${count}}</p>
+      <button onClick={${() => setCount(value => value + 1)}}>
+        Increment
+      </button>
+    </section>
+  `
+}
 
-createRoot(document.getElementById('root')!).render(view)
+createRoot(document.getElementById('root')!).render(reactJsx`<${App} />`)
 ```
 
 The React runtime shares the same template semantics as `jsx`, except it returns React elements (via `React.createElement`) so you can embed other React components with `<${MyComponent} />` and use hooks/state as usual. The helper lives in a separate subpath so DOM-only consumers never pay the React dependency cost.
@@ -109,6 +136,118 @@ npx http-server test/fixtures/rspack-app -p 4173
 
 Visit `http://localhost:4173` (or whichever port you pick) to interact with the Lit + React demo.
 
+## Node / SSR usage
+
+Import the dedicated Node entry (`@knighted/jsx/node`) when you want to run the template tag inside bare Node.js. It automatically bootstraps a DOM shim by loading either `linkedom` or `jsdom` (install one of them to opt in) and then re-exports the usual helpers so you can keep authoring JSX in the same way:
+
+```ts
+import { jsx } from '@knighted/jsx/node'
+import { reactJsx } from '@knighted/jsx/node/react'
+import { renderToString } from 'react-dom/server'
+
+const Badge = ({ label }: { label: string }) =>
+  reactJsx`
+    <button type="button">React says: {${label}}</button>
+  `
+
+const reactMarkup = renderToString(
+  reactJsx`
+    <${Badge} label={${'Server-only'}} />
+  `,
+)
+
+const shell = jsx`
+  <main>
+    <section dangerouslySetInnerHTML={${{ __html: reactMarkup }}}></section>
+  </main>
+`
+
+console.log(shell.outerHTML)
+```
+
+> [!NOTE]
+> The Node entry tries `linkedom` first and falls back to `jsdom`. Install whichever shim you prefer (both are optional peer dependencies) and, if needed, set `KNIGHTED_JSX_NODE_SHIM=jsdom` or `linkedom` to force a specific one.
+
+This repository ships a ready-to-run fixture under `test/fixtures/node-ssr` that uses the Node entry to render a Lit shell plus a React subtree through `ReactDOMServer.renderToString`. Run `npm run build` once to emit `dist/`, then execute `npm run demo:node-ssr` to log the generated markup.
+
+## Next.js integration
+
+> [!IMPORTANT]
+> Next already compiles `.tsx/.jsx` files, so you do not need this helper to author regular components. The loader only adds value when you want to reuse the tagged template runtime during SSR—mixing DOM nodes built by `jsx` with React markup, rendering shared utilities on the server, or processing tagged templates outside the usual component pipeline.
+
+Next (and Remix/other Webpack-based SSR stacks) can run the loader by adding a post-loader to the framework config so the template tags are rewritten after SWC/Babel transpilation. The fixture under `test/fixtures/next-app` ships a complete example that mixes DOM and React helpers during SSR so you can pre-render DOM snippets (for emails, HTML streams, CMS content, etc.) while still returning React components from your pages. The important bits live in `next.config.mjs`:
+
+```js
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const repoRoot = path.resolve(__dirname, '../../..')
+const distDir = path.join(repoRoot, 'dist')
+
+export default {
+  output: 'export',
+  webpack(config) {
+    config.resolve.alias = {
+      ...(config.resolve.alias ?? {}),
+      '@knighted/jsx': path.join(distDir, 'index.js'),
+      '@knighted/jsx/react': path.join(distDir, 'react/index.js'),
+    }
+
+    config.module.rules.push({
+      test: /\.[jt]sx?$/,
+      include: path.join(__dirname, 'pages'),
+      enforce: 'post',
+      use: [{ loader: path.join(distDir, 'loader/jsx.js') }],
+    })
+
+    return config
+  },
+}
+```
+
+Inside `pages/index.tsx` you can freely mix the helpers. The snippet below uses `jsx` on the server to prebuild a DOM fragment and then injects that HTML alongside a normal React component on the client:
+
+```ts
+import type { GetServerSideProps } from 'next'
+import { jsx } from '@knighted/jsx'
+import { reactJsx } from '@knighted/jsx/react'
+
+const buildDomShell = () =>
+  jsx`
+    <section data-kind="dom-runtime">
+      <h2>DOM runtime</h2>
+      <p>Rendered as static HTML on the server</p>
+    </section>
+  `
+
+export const getServerSideProps: GetServerSideProps = async () => {
+  return {
+    props: {
+      domShell: buildDomShell().outerHTML,
+    },
+  }
+}
+
+const ReactBadge = () =>
+  reactJsx`
+    <button type="button">React badge</button>
+  `
+
+type PageProps = { domShell: string }
+
+export default function Page({ domShell }: PageProps) {
+  return reactJsx`
+    <main>
+      <${ReactBadge} />
+      <div dangerouslySetInnerHTML={${{ __html: domShell }}}></div>
+    </main>
+  `
+}
+```
+
+Build the fixture locally with `npx next build test/fixtures/next-app` (or run `npx vitest run test/next-fixture.test.ts`) to verify the integration end to end. You can adapt the same pattern in `app/` routes, API handlers, or server actions whenever you need DOM output generated by the tagged template runtime.
+
 ### Interpolations
 
 - All dynamic values are provided through standard template literal expressions (`${...}`). Wrap them in JSX braces to keep the syntax valid: `className={${value}}`, `{${items}}`, etc.
@@ -227,7 +366,7 @@ Tradeoffs to keep in mind:
 - **Parser vs tokenizer** – `htm` performs lightweight string tokenization, while `@knighted/jsx` pays a higher one-time parse cost but gains the full JSX grammar (fragments, spread children, nested namespaces) without heuristics. For large or deeply nested templates the WASM-backed parser is typically faster and more accurate than string slicing.
 - **DOM-first rendering** – this runtime builds DOM nodes directly, so the cost after parsing is mostly attribute assignment and child insertion. `htm` usually feeds a virtual DOM/hyperscript factory (e.g., Preact’s `h`), which may add an extra abstraction layer before hitting the DOM.
 - **Bundle size** – including the parser and WASM binding is heavier than `htm`’s ~1 kB tokenizer. If you just need hyperscript sugar, `htm` stays leaner; if you value real JSX semantics without a build step, the extra kilobytes buy you correctness and speed on complex trees.
-  - **Actual size** – the default `dist/jsx.js` bundle is ~13.9 kB raw / ~3.6 kB min+gzip, while the new `@knighted/jsx/lite` entry is ~5.7 kB raw / ~2.5 kB min+gzip. `htm` weighs in at roughly 0.7 kB min+gzip, so the lite entry narrows the gap to ~1.8 kB for production payloads.
+  - **Actual size** – as of `v1.2.0-rc.1` the default `dist/jsx.js` bundle is ~9.0 kB raw / ~2.3 kB min+gzip, while the `@knighted/jsx/lite` entry stays ~5.7 kB raw / ~2.5 kB min+gzip. `htm` weighs in at roughly 0.7 kB min+gzip, so the lite entry narrows the gap to ~1.8 kB for production payloads.
 
 In short, `@knighted/jsx` trades a slightly larger runtime for the ability to parse genuine JSX with native performance, whereas `htm` favors minimal footprint and hyperscript integration. Pick the tool that aligns with your rendering stack and performance envelope.
 

package/dist/cjs/node/bootstrap.cjs

@@ -0,0 +1,83 @@
+const DOM_TEMPLATE = '<!doctype html><html><body></body></html>';
+const GLOBAL_KEYS = [
+    'window',
+    'self',
+    'document',
+    'HTMLElement',
+    'Element',
+    'Node',
+    'DocumentFragment',
+    'customElements',
+    'Text',
+    'Comment',
+    'MutationObserver',
+    'navigator',
+];
+const hasDom = () => typeof document !== 'undefined' && typeof document.createElement === 'function';
+const assignGlobalTargets = (windowObj) => {
+    const target = globalThis;
+    const source = windowObj;
+    GLOBAL_KEYS.forEach(key => {
+        if (target[key] === undefined && source[key] !== undefined) {
+            target[key] = source[key];
+        }
+    });
+};
+const loadLinkedom = async () => {
+    const { parseHTML } = await import('linkedom');
+    const { window } = parseHTML(DOM_TEMPLATE);
+    return window;
+};
+const loadJsdom = async () => {
+    const { JSDOM } = await import('jsdom');
+    const { window } = new JSDOM(DOM_TEMPLATE);
+    return window;
+};
+const parsePreference = () => {
+    const value = typeof process !== 'undefined' && process.env?.KNIGHTED_JSX_NODE_SHIM
+        ? process.env.KNIGHTED_JSX_NODE_SHIM.toLowerCase()
+        : undefined;
+    if (value === 'linkedom' || value === 'jsdom') {
+        return value;
+    }
+    return 'auto';
+};
+const selectLoaders = () => {
+    const pref = parsePreference();
+    if (pref === 'linkedom') {
+        return [loadLinkedom, loadJsdom];
+    }
+    if (pref === 'jsdom') {
+        return [loadJsdom, loadLinkedom];
+    }
+    return [loadLinkedom, loadJsdom];
+};
+const createShimWindow = async () => {
+    const errors = [];
+    for (const loader of selectLoaders()) {
+        try {
+            return await loader();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+    }
+    const help = 'Unable to bootstrap a DOM-like environment. Install "linkedom" or "jsdom" (both optional peer dependencies) or set KNIGHTED_JSX_NODE_SHIM to pick one explicitly.';
+    throw new AggregateError(errors, help);
+};
+let bootstrapPromise = null;
+export const ensureNodeDom = async () => {
+    if (hasDom()) {
+        return;
+    }
+    if (!bootstrapPromise) {
+        bootstrapPromise = (async () => {
+            const windowObj = await createShimWindow();
+            assignGlobalTargets(windowObj);
+        })().catch(error => {
+            bootstrapPromise = null;
+            throw error;
+        });
+    }
+    return bootstrapPromise;
+};

package/dist/cjs/node/bootstrap.d.cts

@@ -0,0 +1 @@
+export declare const ensureNodeDom: () => Promise<void>;

package/dist/cjs/node/index.cjs

@@ -0,0 +1,4 @@
+import { ensureNodeDom } from './bootstrap.cjs';
+import { jsx as baseJsx } from '../jsx.cjs';
+await ensureNodeDom();
+export const jsx = baseJsx;

package/dist/cjs/node/index.d.cts

@@ -0,0 +1,2 @@
+export declare const jsx: (templates: TemplateStringsArray, ...values: unknown[]) => import("../jsx.cjs").JsxRenderable;
+export type { JsxRenderable, JsxComponent } from '../jsx.cjs';

package/dist/cjs/node/react/index.cjs

@@ -0,0 +1 @@
+export { reactJsx } from '../../react/react-jsx.cjs';

package/dist/cjs/node/react/index.d.cts

@@ -0,0 +1,2 @@
+export { reactJsx } from '../../react/react-jsx.cjs';
+export type { ReactJsxComponent } from '../../react/react-jsx.cjs';

package/dist/node/bootstrap.d.ts

@@ -0,0 +1 @@
+export declare const ensureNodeDom: () => Promise<void>;

package/dist/node/bootstrap.js

@@ -0,0 +1,83 @@
+const DOM_TEMPLATE = '<!doctype html><html><body></body></html>';
+const GLOBAL_KEYS = [
+    'window',
+    'self',
+    'document',
+    'HTMLElement',
+    'Element',
+    'Node',
+    'DocumentFragment',
+    'customElements',
+    'Text',
+    'Comment',
+    'MutationObserver',
+    'navigator',
+];
+const hasDom = () => typeof document !== 'undefined' && typeof document.createElement === 'function';
+const assignGlobalTargets = (windowObj) => {
+    const target = globalThis;
+    const source = windowObj;
+    GLOBAL_KEYS.forEach(key => {
+        if (target[key] === undefined && source[key] !== undefined) {
+            target[key] = source[key];
+        }
+    });
+};
+const loadLinkedom = async () => {
+    const { parseHTML } = await import('linkedom');
+    const { window } = parseHTML(DOM_TEMPLATE);
+    return window;
+};
+const loadJsdom = async () => {
+    const { JSDOM } = await import('jsdom');
+    const { window } = new JSDOM(DOM_TEMPLATE);
+    return window;
+};
+const parsePreference = () => {
+    const value = typeof process !== 'undefined' && process.env?.KNIGHTED_JSX_NODE_SHIM
+        ? process.env.KNIGHTED_JSX_NODE_SHIM.toLowerCase()
+        : undefined;
+    if (value === 'linkedom' || value === 'jsdom') {
+        return value;
+    }
+    return 'auto';
+};
+const selectLoaders = () => {
+    const pref = parsePreference();
+    if (pref === 'linkedom') {
+        return [loadLinkedom, loadJsdom];
+    }
+    if (pref === 'jsdom') {
+        return [loadJsdom, loadLinkedom];
+    }
+    return [loadLinkedom, loadJsdom];
+};
+const createShimWindow = async () => {
+    const errors = [];
+    for (const loader of selectLoaders()) {
+        try {
+            return await loader();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+    }
+    const help = 'Unable to bootstrap a DOM-like environment. Install "linkedom" or "jsdom" (both optional peer dependencies) or set KNIGHTED_JSX_NODE_SHIM to pick one explicitly.';
+    throw new AggregateError(errors, help);
+};
+let bootstrapPromise = null;
+export const ensureNodeDom = async () => {
+    if (hasDom()) {
+        return;
+    }
+    if (!bootstrapPromise) {
+        bootstrapPromise = (async () => {
+            const windowObj = await createShimWindow();
+            assignGlobalTargets(windowObj);
+        })().catch(error => {
+            bootstrapPromise = null;
+            throw error;
+        });
+    }
+    return bootstrapPromise;
+};

package/dist/node/index.d.ts

@@ -0,0 +1,2 @@
+export declare const jsx: (templates: TemplateStringsArray, ...values: unknown[]) => import("../jsx.js").JsxRenderable;
+export type { JsxRenderable, JsxComponent } from '../jsx.js';

package/dist/node/index.js

@@ -0,0 +1,4 @@
+import { ensureNodeDom } from './bootstrap.js';
+import { jsx as baseJsx } from '../jsx.js';
+await ensureNodeDom();
+export const jsx = baseJsx;

package/dist/node/react/index.d.ts

@@ -0,0 +1,2 @@
+export { reactJsx } from '../../react/react-jsx.js';
+export type { ReactJsxComponent } from '../../react/react-jsx.js';

package/dist/node/react/index.js

@@ -0,0 +1 @@
+export { reactJsx } from '../../react/react-jsx.js';

package/package.json

@@ -1,15 +1,18 @@
 {
   "name": "@knighted/jsx",
-  "version": "1.2.0-rc.0",
-  "description": "A simple JSX transpiler that runs in node.js or the browser.",
+  "version": "1.2.0-rc.1",
+  "description": "Runtime JSX tagged template that renders DOM or React trees anywhere without a build step.",
   "keywords": [
-    "jsx browser transform",
-    "jsx transpiler",
-    "jsx compiler",
-    "jsx parser",
     "jsx runtime",
-    "jsx node",
-    "jsx"
+    "jsx template literal",
+    "tagged template",
+    "no-build jsx",
+    "dom runtime",
+    "react runtime",
+    "ssr",
+    "lit",
+    "webpack loader",
+    "oxc parser"
   ],
   "type": "module",
   "main": "./dist/index.js",
@@ -30,6 +33,16 @@
       "import": "./dist/react/index.js",
       "default": "./dist/react/index.js"
     },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.js",
+      "default": "./dist/node/index.js"
+    },
+    "./node/react": {
+      "types": "./dist/node/react/index.d.ts",
+      "import": "./dist/node/react/index.js",
+      "default": "./dist/node/react/index.js"
+    },
     "./loader": {
       "import": "./dist/loader/jsx.js",
       "default": "./dist/loader/jsx.js"
@@ -51,6 +64,7 @@
     "test": "vitest run --coverage",
     "test:watch": "vitest",
     "build:fixture": "node scripts/build-rspack-fixture.mjs",
+    "demo:node-ssr": "node test/fixtures/node-ssr/render.mjs",
     "dev": "vite dev --config vite.config.ts",
     "build:demo": "vite build --config vite.config.ts",
     "preview": "vite preview --config vite.config.ts",
@@ -61,15 +75,19 @@
   "devDependencies": {
     "@eslint/js": "^9.39.1",
     "@knighted/duel": "^2.1.6",
+    "@types/node": "^22.10.1",
     "@rspack/core": "^1.0.5",
     "@types/jsdom": "^27.0.0",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
     "@vitest/coverage-v8": "^4.0.14",
     "eslint": "^9.39.1",
+    "eslint-plugin-n": "^17.10.3",
+    "@oxc-project/types": "^0.99.0",
     "http-server": "^14.1.1",
     "jsdom": "^27.2.0",
     "lit": "^3.2.1",
+    "next": "^16.0.0",
     "prettier": "^3.7.3",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -85,11 +103,19 @@
     "oxc-parser": "^0.99.0"
   },
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "jsdom": "*",
+    "linkedom": "*"
   },
   "peerDependenciesMeta": {
     "react": {
       "optional": true
+    },
+    "jsdom": {
+      "optional": true
+    },
+    "linkedom": {
+      "optional": true
     }
   },
   "optionalDependencies": {