NeonJSX

NeonJSX is a tiny JSX runtime with a straightforward render pipeline. It turns
JSX into lightweight virtual nodes, then renders them to real DOM nodes with a
single pass. No diffing, no reconciliation, no hooks, just the essentials.

Features

- Small, dependency-free runtime
- Classic JSX pragma support (h / Fragment)
- Simple DOM renderer (render)
- CSS loading with browser cache optimization (css)
- Dynamic component loading (lazy / Suspense)
- TypeScript-friendly, ESM-first

Compile TSX/JSX (your app)

NeonJSX is a runtime only. You bring the compiler, and it should use the classic
JSX transform with h and Fragment.

Complete example (esbuild)

A full, minimal app you can copy into a new directory.

Project layout:
``
neonjsx-example/
package.json
tsconfig.json
src/
index.tsx
public/
index.html
app.css
`

package.json:
`json
{
"name": "neonjsx-example",
"private": true,
"type": "module",
"scripts": {
"build": "esbuild src/index.tsx --bundle --format=esm --platform=browser --jsx=transform --jsx-factory=h --jsx-fragment=Fragment --outfile=public/app.js"
},
"dependencies": {
"@nutsloop/neonjsx": "^1.5.1"
},
"devDependencies": {
"esbuild": "^0.27.2"
}
}
`

tsconfig.json (editor types only):
`json
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"moduleResolution": "bundler",
"jsx": "react-jsx",
"jsxImportSource": "@nutsloop/neonjsx",
"strict": true
},
"include": ["src"]
}
`

src/index.tsx:
`ts
import { render, css } from '@nutsloop/neonjsx';

const App = () => {
css('./app.css'); // URL-based, browser cached
css('.highlight { color: blue; }', { inline: true }); // Inline CSS
return (


NeonJSX

Runtime-only JSX, compiled by your toolchain.

);
};

render(, document.getElementById('root')!);
`

public/index.html:
`html














`

public/app.css:
`css
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}

body {
font-family: system-ui, sans-serif;
background: #1a1a2e;
color: #eee;
min-height: 100vh;
display: flex;
align-items: center;
justify-content: center;
}

main {
text-align: center;
}

h1 {
font-size: 2.5rem;
margin-bottom: 0.5rem;
}
`

Run it:
`bash
npm install
npm run build
`

For a complete example with lazy loading, Suspense, trigger-based loading patterns, and animated spinners, see docs/README.md.

To download only the example:
`bash
git clone --depth 1 --filter=blob:none --sparse https://github.com/nutsloop/neonjsx.js.git
cd neonjsx.js
git sparse-checkout set docs
`

API

$3

Creates a virtual node. This is the JSX factory function.

$3

Collects children without adding an extra DOM element.

$3

Initial mount only. Clears the parent and appends the rendered DOM tree.
Use this when you bootstrap the app at first page load and you want the
root container to represent the whole application.

Why keep render()?
- It is synchronous and simple, which is ideal for the first mount.
- It communicates that this is the primary app root, not a dynamic insert.
- It keeps existing examples and mental models for app startup intact.

For dynamic updates inside existing DOM, use inject() or mount().

$3


Async root mount with an explicit lifecycle handle. mount() is the
modern, explicit alternative to render() when you want control over
cleanup and future lifecycle capabilities.

`ts
const root = await mount( , document.getElementById( 'root' )! );
`

What it does today:
- Performs a render() into the container (replace mode).
- Returns a handle with unmount() and cleanup() methods.
- Tracks that the container is a mounted root.

Why use it:
- Clear intent: "this is a mounted root I may later tear down".
- Safer teardown: you can unmount predictably, even across routes or hot reloads.
- Forward compatible: the handle gives us space to add updates or teardown hooks.

$3

Async teardown of a mounted root container.

`ts
await unmount( document.getElementById( 'root' )! );
`

Current behavior:
- Clears the container.
- Removes the container from the internal mounted registry.

$3


Async cleanup alias for unmount(). This is the semantic "end of lifecycle"
operation you can call when you want to ensure the container is empty and
the mount is discarded.

`ts
await cleanup( document.getElementById( 'root' )! );
`

Why both unmount and cleanup?
- unmount() is lifecycle terminology that matches other UI runtimes.
- cleanup() reads more like a finalization step, especially in async flows.

$3

Async injection for dynamic content inside an existing DOM container.
This is ideal for spinners, toasts, dialogs, or any UI that lives inside
an already-mounted part of the page.

`ts
await inject( , contentEl, { mode: 'append' } );
`

Modes:
- replace (default): same DOM behavior as render() but without implying
this is the root app mount.
- append: inserts the rendered nodes after the current children.
- prepend: inserts the rendered nodes before the current children.

Notes:
- inject() is async so the API can evolve (cleanup hooks, async rendering,
or future diffing) without breaking your call sites.
- Use eject() to remove injected content when you are done.

$3

Async cleanup for injected content. Clears the parent container.

`ts
await eject( contentEl );
`

$3

Think of the DOM in two layers: root app mounts and local injections.

Root mount (app lifecycle):
- Use render() for the simplest initial boot.
- Use mount() if you want explicit teardown and a returned handle.
- Use unmount() or cleanup() to remove the root app.

Local injection (dynamic UI inside the app):
- Use inject() to place content inside an existing DOM container.
- Use eject() to clear that container.

This split keeps the intent clear:
- render()/mount() communicate "this is the app root".
- inject() communicates "this is a dynamic insertion".

$3

Loads CSS on first component render with deduplication.

`ts
css('/styles/button.css'); // URL-based (browser cached)
css('.btn { color: red; }', { inline: true }); // Inline CSS
`

- URL mode: Injects into
- Inline mode: Injects