How I compile React-shaped TSX without React or hydration

bunzzeok — Sat, 25 Jul 2026 12:23:04 +0000

I started building Kudzu while making static websites with AI.

AI coding tools have become very good at producing React-shaped TSX, and I have become used to reviewing code in that form. Function components, props, JSX, and event handlers are often easier for me to understand and verify than scattered DOM queries and imperative JavaScript mutations.

But I was still building static pages.

I wanted to keep TSX as the authoring and code-review format without automatically shipping React, a virtual DOM, hydration, or a browser-side component tree.

Kudzu grew from that idea:

Write familiar TSX, execute components during the build, and ship ordinary HTML with only the JavaScript each route actually needs.

Kudzu is an experimental, HTML-first TSX framework.

Website: kudzujs.cloud

GitHub: github.com/kudzujs/kudzu

The problem I wanted to solve

Consider a blog, documentation site, newsletter, or product landing page.

Most of the page is already known during the build:

headings;
navigation;
articles;
images;
metadata;
product descriptions;
documentation content.

TSX is a convenient way to author and review that structure.

function PostCard({ title, description, href }: {
  title: string
  description: string
  href: string
}) {
  return (
    <article>
      <h2><a href={href}>{title}</a></h2>
      <p>{description}</p>
    </article>
  )
}

The component model is useful for authoring, but that does not necessarily mean the browser needs a component runtime.

For a static page, I wanted the output to remain ordinary HTML.

<article>
  <h2><a href="/posts/hello">Hello</a></h2>
  <p>My first article.</p>
</article>

I also wanted interactive pages to receive only the JavaScript required for their actual behavior.

Kudzu's model

Kudzu treats components as build-time authoring units.

React-shaped TSX
        ↓
Kudzu compiler
        ↓
Static HTML + CSS + capability-specific ESM

Function components execute during the build.

The browser does not receive:

the component functions;
React;
a virtual DOM;
a hydration pass;
a retained component tree;
a general rerender loop.

A completely static route receives no client JavaScript.

A static page

A Kudzu page lives in src/pages.

// src/pages/index.tsx

export default function HomePage() {
  return (
    <main>
      <h1>Hello from Kudzu</h1>
      <p>This page becomes static HTML.</p>
    </main>
  )
}

Build the project:

npm run build

The output is written to dist.

dist/
├─ index.html
└─ assets/
   └─ style.css

Because the page has no browser behavior, Kudzu does not add a JavaScript runtime.

Adding state

Kudzu supports a React-shaped useState API.

import { useState } from "@kudzujs/core"

export default function Counter() {
  const [count, setCount] = useState(0)

  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  )
}

The compiler identifies:

the logical state;
the setter;
the event;
the text node bound to the state.

The component is executed during the build to produce the initial HTML.

The browser receives a small behavior plan that updates the relevant DOM node directly.

click
  → update logical state
  → queue a DOM commit
  → patch the bound text node

The browser does not rerun the component.

Immediate logical state

Kudzu deliberately differs from React's state snapshot behavior.

function increaseTwice() {
  setCount(count + 1)
  setCount(count + 1)
}

In Kudzu:

A setter updates logical state immediately.
The next statement reads the latest logical value.
Setters run in source order.
DOM writes are batched until the synchronous turn ends.

The handler above increments the value by two and patches the DOM once.

This model gives event handlers normal sequential JavaScript behavior without requiring a browser component rerender.

Simple commands and normal JavaScript

Kudzu has two event compilation paths.

Simple setter-only handlers compile to compact behavior commands.

<button onClick={() => setCount(count + 1)}>
  Increase
</button>

Normal synchronous or asynchronous handlers compile to external ESM.

async function loadStatus() {
  setStatus("loading")

  try {
    const response = await fetch("/api/status")
    const result = await response.json()
    setStatus(result.status)
  } catch {
    setStatus("failed")
  }
}

Kudzu does not use:

eval;
new Function;
inline executable JavaScript;
hydration.

Relative TypeScript helpers can also be bundled into the generated handler module.

import { normalizeStatus } from "../lib/status"

async function loadStatus() {
  const response = await fetch("/api/status")
  const result = await response.json()

  setStatus(normalizeStatus(result))
}

Direct DOM bindings

State can be used in text, attributes, styles, and form properties.

const [open, setOpen] = useState(false)

return (
  <button
    className={open ? "active" : "idle"}
    aria-expanded={open}
    onClick={() => setOpen(!open)}
  >
    {open ? "Close" : "Open"}
  </button>
)

Kudzu compiles the expressions into direct DOM updates.

open changes
  → patch class
  → patch aria-expanded
  → patch text

The entire component is not rerendered.

Conditional DOM

Inline conditional children compile to bounded DOM ranges.

const [open, setOpen] = useState(false)

return (
  <>
    <button onClick={() => setOpen(!open)}>
      Toggle menu
    </button>

    {open && (
      <nav>
        <a href="/docs">Docs</a>
        <a href="/example">Examples</a>
      </nav>
    )}
  </>
)

Both branches are prepared during the build. The browser mounts or removes only the relevant DOM range.

There is still no virtual DOM or component tree.

Keyed lists

Kudzu also supports a constrained form of keyed list rendering.

const [items, setItems] = useState([
  { id: 1, name: "Oak" },
  { id: 2, name: "Pine" }
])

return (
  <ul>
    {items.map(item => (
      <li key={item.id}>
        {item.name}
        <button
          onClick={() =>
            setItems(items.filter(entry => entry.id !== item.id))
          }
        >
          Remove
        </button>
      </li>
    ))}
  </ul>
)

The initial list is emitted as static HTML.

When state changes, Kudzu moves, inserts, updates, or removes the keyed DOM nodes directly.

Existing keyed nodes are preserved instead of remounted.

Build-time data

Async components can load data during the build.

export default async function ProductsPage() {
  const products = await fetch(
    "https://example.com/api/products"
  ).then(response => response.json())

  return (
    <main>
      <h1>Products</h1>

      <ul>
        {products.map(product => (
          <li>{product.name}</li>
        ))}
      </ul>
    </main>
  )
}

When the route and data are available during the build, the result is complete static HTML.

No browser fetch or hydration is required.

Dynamic static routes

Build-known dynamic routes use getStaticPaths().

// src/pages/posts/[slug].tsx

export function getStaticPaths() {
  return [
    {
      params: { slug: "hello-kudzu" },
      props: { title: "Hello Kudzu" }
    },
    {
      params: { slug: "static-html" },
      props: { title: "Static HTML" }
    }
  ]
}

export default function Post({
  title
}: {
  title: string
}) {
  return <h1>{title}</h1>
}

The build produces:

dist/posts/hello-kudzu/index.html
dist/posts/static-html/index.html

The result can be deployed to an ordinary static host.

Browser-only effects

Sometimes data or browser APIs are only available after the document loads.

Kudzu supports a deliberately constrained useEffect form.

import { useEffect, useState } from "@kudzujs/core"

export default function StatusPage() {
  const [status, setStatus] = useState("loading")

  useEffect(() => {
    fetch("/api/status")
      .then(response => response.json())
      .then(result => setStatus(result.status))
  }, [])

  return <p>Status: {status}</p>
}

The effect is not executed during static rendering.

Kudzu emits a route-specific effect entry that updates the existing logical state and bound DOM nodes.

The component itself is not shipped or rerun.

Capability-specific output

Kudzu does not give every interactive route the same runtime.

A route receives only the capabilities it uses.

Static route          → HTML only
State commands        → compact behavior runtime
Reactive bindings     → binding capability
Conditional DOM       → bounded DOM operations
Keyed lists           → list capability
Normal handlers       → external handler ESM
Effects               → route-specific effect entry
Runtime parameters    → route-specific pathname reader

A static route remains JavaScript-free even if another route in the same project is interactive.

Static output and Cloudflare

Kudzu writes deployable artifacts to dist.

A minimal Cloudflare configuration looks like this:

{
  "name": "my-kudzu-site",
  "compatibility_date": "2026-07-20",
  "assets": {
    "directory": "dist"
  }
}

Build and deploy:

npm run build
npx wrangler deploy

The Kudzu website itself is deployed using Cloudflare static assets.

The project also uses build-time generation for:

canonical URLs;
sitemap entries;
robots metadata;
structured data;
static blog routes.

Why not just write vanilla JavaScript?

Vanilla JavaScript is not the problem.

For small behavior, it is often the smallest and best browser output.

The problem I was trying to solve was authoring and review.

When working with AI-generated code, I found this form easier to inspect:

<PostCard
  title={post.title}
  description={post.description}
  href={`/posts/${post.slug}`}
/>

than a collection of unrelated operations:

const article = document.createElement("article")
const heading = document.createElement("h2")
const link = document.createElement("a")

link.href = `/posts/${post.slug}`
link.textContent = post.title
heading.append(link)
article.append(heading)

The browser may ultimately need ordinary DOM operations.

I just did not want to author and review the entire site at that level.

Kudzu uses TSX as the input language and ordinary HTML and DOM operations as the output.

What Kudzu is not

Kudzu is not a drop-in React replacement.

It supports a statically analyzable React-shaped subset.

Unsupported patterns fail during the build instead of silently causing Kudzu to ship a general component runtime.

Kudzu currently does not provide:

arbitrary React package compatibility;
a virtual DOM;
request-time SSR;
server actions;
a default SPA router;
Suspense semantics;
concurrent rendering;
a general browser component rerender loop.

The goal is not to run every React application unchanged.

The goal is to preserve familiar TSX authoring where it can be compiled safely into static HTML and direct browser behavior.

Current status

Kudzu is experimental, and the supported TSX surface may still change.

The current implementation includes:

function components;
props and children;
fragments;
static and dynamic routes;
async build-time components;
primitive and serializable object state;
reactive text and attributes;
controlled form properties;
conditional DOM;
keyed lists;
context;
DOM refs;
synchronous and asynchronous handlers;
relative TypeScript helpers;
mount effects;
primitive effect dependencies;
runtime path parameters;
Cloudflare static deployment.

I am especially interested in feedback about:

the compiler model;
migration from conventional React-shaped code;
unsupported patterns that need better diagnostics;
generated JavaScript size;
immediate logical state semantics;
real static-site use cases.

Try Kudzu

Create a project:

npm create kudzu@latest my-app
cd my-app
npm run dev

Build the static output:

npm run build

The generated files are available in:

dist/

The build execution plan is available in:

.kudzu/kudzu-plan.json

Links

Website: https://kudzujs.cloud/

Examples: https://kudzujs.cloud/example

Documentation: https://kudzujs.cloud/docs

GitHub: https://github.com/kudzujs/kudzu

npm: https://www.npmjs.com/package/@kudzujs/core

DEV Community: bunzzeok