Getting started

Create a project

Run the project generator:

npx create-natui-app@latest

With no directory argument, the CLI asks for a project directory and suggests natui-app. You can also provide the name directly:

npx create-natui-app@latest my-app

The generator creates a TypeScript application, installs dependencies with the detected package manager, and writes:

• src/App.tsx for the React component tree
• src/main.tsx as the shared development and packaging entry
• natui.app.json for application identity, entry, output, and icon paths
• Native assets/AppIcon.icns and multi-image assets/AppIcon.ico defaults

Use --package-manager npm|pnpm|yarn|bun to select a package manager or --no-install to create the project without installing dependencies.

Start developing

cd my-app
npm run dev

The first launch downloads the prebuilt native host for the installed release from its GitHub release, verifies the archive checksum, and caches the host per user. Later launches start instantly from that cache. To download ahead of time, for example when preparing an offline machine, run:

npx natui host install

Behind a corporate proxy, run the download with NODE_USE_ENV_PROXY=1 (Node 22.18 or newer) so Node's fetch honors HTTPS_PROXY.

Prefer a self-built host? Build the macOS or Windows host from the NatUI source repository and set the NATUI_HOST environment variable to that executable; it always wins over the download cache.

natui dev reads the entry from natui.app.json, bundles its local source graph, and applies React Fast Refresh to the existing native window.

Continue with the first app walkthrough, then explore the component catalog. Use source setup when contributing to NatUI itself or building the included examples.

The JavaScript runtime validates the protocol version and platform reported by the host during startup. Build both sides from the same release for the simplest known-compatible setup, although any host and renderer that both implement protocol version 1 can interoperate.