# natui/dev

> Start and control the NatUI development server programmatically.

Canonical: https://natui.dev/docs/api/dev

The `natui/dev` entrypoint exposes the same state-preserving development
server used by the `natui dev` command.

## createDevServer [#createdevserver]

```ts typecheck
import { createDevServer } from 'natui/dev';

const server = await createDevServer({
  root: process.cwd(),
  entry: 'src/main.tsx',
});

const close = async () => {
  await server.close();
};

process.once('SIGINT', () => void close());
process.once('SIGTERM', () => void close());
```

The watcher keeps the process alive. The signal handlers use the returned
server handle to cleanly stop the watcher and native host.

The executable entry must call `run()` once. The server watches the
application's local source graph, applies React Fast Refresh after successful
builds, and keeps the previous native UI mounted after a build or evaluation
error.

### DevServerOptions


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `entry` | `string \| undefined` | No | Executable application entry. Defaults to src/main.tsx. |
| `root` | `string \| undefined` | No | Project root used for resolution and watching. Defaults to process.cwd(). |
| `log` | `((message: string) => void) \| undefined` | No | Receives concise status output. Defaults to console.error. |

| Property | Purpose                                                   |
| -------- | --------------------------------------------------------- |
| `entry`  | Executable entry path, relative to `root` unless absolute |
| `root`   | Project root for module resolution and the watcher        |
| `log`    | Receives build, mount, refresh, and error status text     |

## NatuiDevServer [#natuidevserver]

### NatuiDevServer


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `entry` | `string` | Yes | Absolute entry file being watched. |
| `close` | `() => Promise<void>` | Yes | Stop watching, unmount the app, and terminate the native host. |

`close()` stops the build watcher, unmounts React, asks the native host to quit,
and removes temporary build output. Calling it more than once is safe.

The server runs its module builder in-process and does not open an HTTP port.