Lightweight JSX runtime.
npm install @nutsloop/neonjsxNeonJSX 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.
h / Fragment)render)css)lazy / Suspense)h and Fragment.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 = () => { Runtime-only JSX, compiled by your toolchain.
css('./app.css'); // URL-based, browser cached
css('.highlight { color: blue; }', { inline: true }); // Inline CSS
return (
NeonJSX
);
};
render(
`
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
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().
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