Quick start

Run without --import

Register the loader directly in your JavaScript entry point.

Node.js first needs a handler for JSX/TSX imports. Registration installs that handler once per process. Choose one approach: register in app.js before a dynamic import, use a separate bootstrap.js, or pass --import when starting Node.

Importing "jtsx-loader" registers the loader; the same module exports raw and renderToString. For explicit registration, use register.js as shown below. Load .jsx/.tsx with await import() afterwards. A static template import in the same entry file is linked too early, even if written below registration.

bootstrap.js is a small entry file: it registers the loader and then starts server.js. That lets server.js use import Page from "./Page.jsx". Find server.js in “Express & Fastify”. Use jtsx-loader/runtime.js for helpers without registration, including inside jtsx.config.js to avoid a loading cycle.

import 'jtsx-loader/register.js';
await import('./server.js');

node bootstrap.js
# Or the original preload path:
node --import jtsx-loader server.js

Factory in the browser

One JSX component for frontend and backend.

Use Counter.jsx from the quick start and the three files below: client.jsx, build-client.mjs and index.html in one directory. Install esbuild, run the build and serve this directory with your local HTTP server. Open index.html over HTTP: the button updates the counter. After changing JSX, rebuild and refresh the page.

Counter.jsx from the quick start is already server-rendered below. The client bundle imports the same file and updates it in the browser. Click the button: the counter changes without a server request or React.

Import the factory from jtsx-loader/browser.js. This entry does not read Node configuration, register loader hooks or require Node polyfills. It exports _jsx, _jsxFragment, _jsxUtils, raw, renderToString and createFactory(options). Root imports also select browser.js in bundlers supporting the browser condition; the explicit path makes configuration predictable.

Compile JSX/TSX ahead of time: browsers do not parse JSX syntax themselves. Set jsxFactory, jsxFragment and inject in esbuild as shown. No React or ReactDOM installation is needed. esbuild runs at build time; the client bundle contains your components and the factory.

The factory produces HTML; your code owns state, DOM and events. This example uses innerHTML and a delegated addEventListener on a stable container. It re-renders rather than hydrating or diffing a virtual DOM: replacing content resets nested DOM state and focus. Choose a suitable DOM update strategy for more complex updates.

Shared components should use data and cross-platform imports only. Keep node:fs on the server and document/window in the client entry. Configure browser factories through createFactory(options), not jtsx.config.js. Await async component calls explicitly, or inject browserAsync.js for automatic nested resolution and use renderToString(await Page()). Existing factory/jsxFactory.js and factory/asyncFactory.js package imports also select client adapters under the browser condition.

import { renderToString } from 'jtsx-loader/browser.js';
import Counter from './Counter.jsx';

const root = document.querySelector('#client-demo');
const ru = root.dataset.lang === 'ru';
let count = 0;

function render() {
    root.innerHTML = renderToString(
        <Counter
            count={count}
            label={
                ru
                    ? 'Один компонент. Две среды.'
                    : 'One component. Two environments.'
            }
            buttonLabel={ru ? 'Добавить один' : 'Add one'}
        />,
    );
}

// Keep the listener on the stable container when replacing its content.
root.addEventListener('click', (event) => {
    if (event.target.closest('[data-increment]')) {
        count += 1;
        render();
    }
});
render();

import { build } from 'esbuild';
import { fileURLToPath } from 'node:url';

await build({
    entryPoints: ['client.jsx'],
    bundle: true,
    platform: 'browser',
    format: 'esm',
    target: 'es2020',
    jsxFactory: '_jsx',
    jsxFragment: '_jsxFragment',
    inject: [fileURLToPath(import.meta.resolve('jtsx-loader/browser.js'))],
    outfile: 'dist/client.js',
});

npm install --save-dev esbuild
node build-client.mjs

<div id="client-demo" data-lang="en"></div>
<script type="module" src="./dist/client.js"></script>

import { createFactory } from 'jtsx-loader/browser.js';
export const { _jsx, _jsxFragment, _jsxUtils } = createFactory({
    rewriteReactAttrs: true,
});
// Use this module as the bundler inject entry instead of browser.js.

Components & layouts

Ordinary functions, props and composition.

A component is a function receiving a props object and returning JSX. <Layout title="Catalog">...</Layout> passes title and nested content as children. The Layout below defines a shared HTML document; the catalog component fills its content. To obtain a string, call renderToString(await Page({ items })) in your server code.

Props reach a component unescaped: values remain data until tag serialization. children is [], one value or an array. Arrays flatten recursively without extra spaces. null, undefined and booleans are omitted; 0 and bigint remain. Add spaces explicitly.

Fragments add no DOM wrapper. Arbitrary object children throw: select a field or explicitly use JSON.stringify. JSX does not install browser event handlers; load client JavaScript separately.

const Layout = ({ title, children }) => <html lang="en">
    <head><title>{title}</title></head>
    <body>{children}</body>
</html>;

export default ({ items }) => <Layout title="Catalog">
    <h1>Catalog</h1>
    <ul>{items.map(item => <li>{item.name}</li>)}</ul>
    {items.length === 0 && <p>No items</p>}
    <>{'A'}{' '}{'B'}</>
</Layout>;

Async rendering

Explicit await, or a factory that awaits nested components.

Declare a component async when it loads data from an API or a file. For a single async component, explicit await is enough and needs no config change. To use nested <Child /> without awaiting each call manually, select the async factory in jtsx.config.js. These are two alternative approaches shown below.

The default factory is synchronous: use {await Child()} for an async component inside a template. A Promise passed to children produces an instruction to await it. Alternatively, select asyncFactory.js below.

The async factory returns a Promise of rendered JSX markup and resolves nested arrays and Promises concurrently in source order. Nested failures reach the outer await. Attribute values and __raw/__escape are not automatically awaited: resolve them first.

const Child = async () => <b>Ready</b>;
export default async () => <main>{await Child()}</main>;

export default {
    injectFactory: true,
    importFactory: "import { _jsx, _jsxFragment, _jsxUtils } from 'jtsx-loader/factory/asyncFactory.js';",
};

const Child = async () => <b>{await Promise.resolve('<Ready>')}</b>;

export default () => <main>
    <Child />
    {[Promise.resolve('A'), ['B', null, false, 0]]}
</main>;

import { renderToString } from 'jtsx-loader';
const { default: Page } = await import('./async.jsx');
console.log(renderToString(await Page()));

node app-async.js

Attributes & CSS

Native HTML names and explicit serialization rules.

Use ordinary class directly in JSX/TSX: <div class="card">. You do not need className or extra configuration, on either the server or the browser. For compatibility, className is also supported and always becomes class.

Other React-style names warn by default; rewriteReactAttrs: true enables replacement. style accepts a string or an object with native CSS names. style={null} is omitted.

true serializes as "true", false is omitted, null becomes "null", and undefined creates a bare attribute. Therefore use the string "false" for aria-expanded. Function-valued attributes are ignored with a warning.

attributeParser is selected by the prefix before a colon and returns a complete trusted HTML fragment. It must escape its own values. Attribute names should come from template code.

<label class="field" for="name">Name</label>
<input id="name" value={'"<&'} disabled={true} />
<div style={{ color: 'red', '--gap': '8px' }} />

import { escapeHtml } from 'jtsx-loader/factory/jsxUtils.js';
export default {
    attributeParser: {
        ac: (name, value) =>
            `data-${name.replaceAll(':', '-')}="${escapeHtml(value)}"`,
    },
};

Configuration

jtsx.config.js

Basic usage needs no configuration file. To change options, create jtsx.config.js beside package.json and export an object with export default. Start Node from that directory. Restart the process after changing configuration: ?reload refreshes templates rather than reconfiguring the loader.

Configuration is read from process.cwd(), not the template directory. A missing file is optional. A broken existing file warns and falls back to defaults; JTSX_STRICT_CONFIG=1 makes it fail. Configuration can run in separate Node contexts: avoid side effects.

When setting esbuildTransformConfig, use injectFactory: true or import the factory manually. Do not combine a manual import of the same names with forced injection. esbuildTransformConfig accepts transform options including minify and target.

export default {
    injectFactory: true,
    esbuildTransformConfig: { minify: true },
};

$env:JTSX_STRICT_CONFIG = "1"
node app.js

Express & Fastify

An HTML string at the HTTP boundary.

Choose one server. For Express, save server.js below and bootstrap.js from “Run without --import” beside Page.jsx and Counter.jsx. Install express, run node bootstrap.js and open http://localhost:3000/. For Fastify, use a separate fastify.js, install fastify and run node fastify.js; this example needs no bootstrap.

On each request, the server calls Page with data, awaits the result and converts it to an HTML string with renderToString(). Pass that string to res.send()/reply.send(): the framework may treat a JSX object as JSON. The handlers below return 404 for an unknown path and 500 if rendering fails.

npm install express
node bootstrap.js

import express from 'express';
import { renderToString } from 'jtsx-loader/runtime.js';
import Page from './Page.jsx';

const app = express();
app.get('/', async (req, res, next) => {
    try {
        const html = renderToString(await Page({ title: 'Hello' }));
        res.type('html').send(html);
    } catch (error) {
        next(error);
    }
});
app.use((req, res) => res.status(404).send('Not found'));
app.use((error, req, res, next) => {
    console.error(error);
    if (res.headersSent) return next(error);
    res.status(500).send('Internal server error');
});
app.listen(3000);

import Fastify from 'fastify';
import { renderToString } from 'jtsx-loader';
const { default: Page } = await import('./Page.jsx');
const app = Fastify({ logger: true });
app.get('/', async (request, reply) => {
    const html = renderToString(await Page({ title: 'Hello' }));
    return reply.type('text/html').send(html);
});
app.setNotFoundHandler((request, reply) => reply.code(404).send('Not found'));
app.setErrorHandler((error, request, reply) => {
    request.log.error(error);
    reply.code(500).send('Internal server error');
});
await app.listen({ port: 3000 });

npm install fastify
node fastify.js

Static generation

Render to a file without an HTTP server.

Save static.js beside Page.jsx and Counter.jsx from the quick start. Running node static.js creates dist/index.html and exits. Open the file or deploy dist to static hosting. Run the generator again after changing a template: existing HTML files do not update themselves.

This example needs no --import flag. Do not swallow build errors: unavailable data or a broken template should produce a non-zero exit. Directory creation and writing are explicit. Add html/head/body to Page for a complete document.

import { mkdir, writeFile } from 'node:fs/promises';
import { renderToString } from 'jtsx-loader';

const { default: Page } = await import('./Page.jsx');
await mkdir('dist', { recursive: true });
const html = '<!doctype html>\n' + renderToString(await Page({ title: 'Hello' }));
await writeFile('dist/index.html', html);

node static.js

JSX / TSX

Transpilation with esbuild, without type checking.

The loader handles .jsx and .tsx. Ordinary .ts files are delegated to Node, whose support varies by version. Include file extensions in imports. Run type checking separately; a complete JSX namespace and prop typings are not yet shipped. A successful TSX render is not a TypeScript check.

type Props = { title: string; count: number };
export default ({ title, count }: Props) => <section>
    <h1>{title}</h1>
    <p>{count}</p>
</section>;

Development & diagnostics

See template changes and identify the cause of an error.

Node.js caches imported modules in memory. While the server keeps running, an ordinary import of the same path returns the already loaded module. Editing the file and refreshing the browser tab do not themselves refresh that module.

There are two ways to see edits: restart Node.js or import the template again with ?reload in the same process. Automatic browser refresh is a separate task; jtsx-loader does not watch files or send live-reload notifications to the browser.

import { renderToString } from 'jtsx-loader';

// Development only: import again for each render, including nested components.
export async function renderPage(props) {
    const { default: Page } = await import('./Page.jsx?reload');
    return renderToString(await Page(props));
}

import { createServer } from 'node:http';
import { renderPage } from './reload.js';

export const server = createServer(async (request, response) => {
    if (request.url !== '/') {
        response.writeHead(404).end('Not found');
        return;
    }
    try {
        const html = await renderPage({ title: 'Live JSX' });
        response.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
        response.end(html);
    } catch (error) {
        console.error(error);
        response.writeHead(500).end('Render failed; check the terminal');
    }
}).listen(Number(process.env.PORT || 3000), '127.0.0.1', () => {
    console.log('Development server: http://localhost:' + server.address().port);
});

node dev-server.js

npm install --save-dev nodemon
npx nodemon --watch . --ext js,mjs,cjs,json,jsx,tsx --ignore dist/ --ignore build/ bootstrap.js

npm install
npm run dev

Common errors and fixes

Escaping & raw()

Strings are text. raw(value) explicitly permits HTML insertion.

Text and ordinary attribute values are escaped by default. JSX results retain their identity as rendered markup, so nested components are not escaped twice. Call renderToString(await Page(props)) at the HTTP, file or logging boundary. Converting child JSX to a string before insertion loses its markup identity.

raw() returns an immutable wrapper and does not sanitize anything. Only use trusted or previously sanitized HTML. raw() does not bypass escaping in attributes. __raw and __escape remain supported; ordinary text no longer needs __escape. Pre-escaped strings are escaped again.

Escaping does not validate URL protocols, dynamic tag/attribute names, CSS or string event handlers. Do not spread untrusted props wholesale. script/style need context-specific handling: raw() can insert trusted source code, but does not make user JavaScript safe.

import { raw } from 'jtsx-loader';

const text = '<b>Hello</b>';
const Text = () => <p>{text}</p>;
const Markup = () => <p>{raw(text)}</p>;

<p>&lt;b&gt;Hello&lt;&#x2F;b&gt;</p>
<p><b>Hello</b></p>

import { raw } from 'jtsx-loader/runtime.js';

// Escape HTML end tags before opting into raw JSON output.
export default ({ value }) => <script type="application/json">
    {raw(JSON.stringify(value).replaceAll('<', '\\u003c'))}
</script>;

Migration from 0.1.15–0.1.18

You can upgrade directly from 0.1.15. Versions 0.1.16–0.1.18 preserved existing behavior; the current API changes default escaping and the JSX result type. Follow the steps below, then review the changes at each stage.

1. Replace direct HTTP/file output with renderToString(await Page(props)).
2. Remove manual escapeHtml calls for ordinary children and attributes. Keep escaping inside attributeParser: its output is inserted as a complete attribute fragment.
3. Wrap intentional HTML strings in raw(html).
4. Do not join/interpolate child JSX into strings before rendering.
5. Account for no implicit spaces and preserved zero.

Installing each intermediate version is unnecessary. From 0.1.15, review both stages below; from 0.1.18, start with the new rendering contract.

This update retains existing deep-import paths, --import registration, configuration, the async factory and ?reload. The complete changelog lives in the repository.

export default {
    injectFactory: true,
    importFactory: "import { _jsx, _jsxFragment, _jsxUtils } from 'jtsx-loader/factory/asyncFactory.js';",
};

const Page = ({ html }) => <main>{html}</main>;
res.type('html').send(await Page({ html: '<b>Hello</b>' }));

import { raw, renderToString } from 'jtsx-loader';
const Page = ({ html }) => <main>{raw(html)}</main>;
res.type('html').send(renderToString(await Page({ html: '<b>Hello</b>' })));

import 'jtsx-loader/register.js';
await import('./server.js');

export default {
    escapeChildren: false,
    escapeAttributes: false,
};