Source setup

Use this path when contributing to NatUI, building a native host, or running the repository verification suites. To start an application, use create-natui-app first.

Prerequisites

• Node.js 22 or newer
• pnpm 11
• Git
• The platform tools described in the macOS or Windows guide

git clone https://github.com/floklein/natui.git
cd natui
corepack enable
pnpm install
pnpm build
pnpm typecheck

pnpm build emits the @natui/core package into packages/natui/dist. The examples resolve the package through the pnpm workspace, so build the package before running a standalone typecheck.

Package the demo

The repository includes a native application packaging workflow:

pnpm package:demo
pnpm verify:package

It reads examples/demo/natui.app.json and produces a native artifact for the current platform and architecture. macOS requires the Swift toolchain. Windows requires the .NET SDK and emits one self-contained EXE that extracts runtime dependencies to a per-user temporary cache when launched.

pnpm verify:package opens the packaged application, validates its handshake and native tree, then exercises the normal close lifecycle. A real desktop window session is required.

See application bundles for configuration and distribution boundaries.

Package exports and CLI

The workspace exposes five package entrypoints:

• @natui/core for components, run, and advanced protocol exports
• @natui/core/components for component-only bundles that avoid Node built-ins
• @natui/core/inproc for the embedded host entrypoint
• @natui/dev for programmatic development-server startup
• @natui/core/config for loading and validating natui.app.json

The package also installs natui dev [entry] for native development with React Fast Refresh. Without a positional entry, it reads entry from natui.app.json, then falls back to src/main.tsx.

@natui/core and create-natui-app are registry packages. Outside a checkout, the runtime downloads the release's prebuilt host on first launch. Inside a checkout, the bridge only uses the host built from these sources, so a stale download can never shadow your build; set NATUI_HOST to point an application elsewhere at your build. The application packager remains a repository-local reference workflow.