Your first app, in React

You know React. Here’s the twist: the same components, hooks and JSX render into a native desktop window, drawn by BUI. There’s no browser, no webview and no Electron. When you’re done, one command turns the app into a single executable of about 5 MB.

You’ll build a counter with a Blender slider, learn the one thing that’s different about hooks here (they hold signals), and ship it.

Set up

What’s in the code

• /** @jsxImportSource @blender-ui/react */ tells the JSX compiler to use BUI’s runtime for this file. For a whole project, set "jsxImportSource": "@blender-ui/react" in tsconfig.json or your bundler’s JSX options instead.
• Host components are HTML elements, as in React DOM: <main>, <span>, <button>. className takes Tailwind classes, and style objects work too.
• <NumberSlider> is one of the Blender components, the real Blender widget. The others are Button, Checkbox, Radio, NumberField, TextField, TextArea, ColorSwatch, Dropdown and ProgressBar.
• onChange fires when the slider’s value changes; e.target.valueAsNumber holds the number.
• render(element, options) opens a window and mounts your component. It returns { app, window, root }.
• styled on the body gives the whole page Blender’s look. Without it, plain elements look like a browser’s.

The twist: hooks hold signals

useState has React’s name, arguments and timing, but the value it gives you is a signal: a box that knows who’s watching it. That changes one thing, for the better:

• Pass the signal into JSX, like {count} or {size}, and a change updates that one text node. Counter doesn’t re-render at all.
• Read .value while rendering, like count.value > 9, and the component re-renders when it changes, as with React.

One rule follows from it: conditions need .value. A signal is an object, so it’s always truthy.

{count.value > 0 && <p>You clicked!</p>}   // right
{count > 0 && <p>You clicked!</p>}         // works in plain JS, but use .value
{count && <p>Always shown</p>}             // wrong: a signal is always truthy

This is why React on BUI costs about what the plain DOM-like API does: clicking Add one changes a single text node, with no new element tree and no diff.

Running on Node.js

Node doesn’t read JSX, so either compile it (any bundler, with jsxImportSource set to @blender-ui/react) or write the same component with createElement, as the repository’s examples/counter.js does:

const { render, createElement: h, useState } = require('@blender-ui/react')

function Counter () {
  const [count, setCount] = useState(0)
  return h('main', { className: 'p-6 flex flex-col gap-3' },
    h('span', null, 'Clicks: ', count),
    h('button', { onClick: () => setCount(c => c + 1) }, 'Add one'))
}

render(h(Counter), { title: 'Counter', width: 420, height: 260 })

node app.js

Ship it as one file

npx bui build app.jsx

This writes app.exe: BUI plus the small QuickJS JavaScript engine, with your bundled app appended. For a small React app on Windows x64, the repository measured a 4.9 MB executable that reaches its first frame in 68 ms.

• Bundling needs Bun installed, even if you run the app on Node. With Bun alone, bunx bui build app.jsx works too.
• Windows builds open no console window. Add --console to see your console.log output.
• QuickJS has no Node modules (fs, net …). If your app needs them, build with --bun for a full Bun runtime (about 115 MB).
• npx bui run app.jsx runs on the QuickJS runtime without making an executable.

The prebuilt runtime is for Windows x64. On other platforms, npm run build in bindings/node builds it from source.

Next steps