UIGenv0.17.0·2026-05-26
Blog

Quick Start

The fastest way to get started with UIGen is using the init command (no installation required).

Step 1: Initialize a project

Create a new UIGen project with a single command:

npx @uigen-dev/cli init my-admin-ui

You'll be prompted for:

  • Path to your existing OpenAPI spec (optional)
  • Whether to initialize a git repository

Or skip prompts with the -y flag:

npx @uigen-dev/cli init my-admin-ui -y

You should see output like:

✨ UIGen Project Initialization

Creating project: my-admin-ui

✓ Created directory structure
✓ Copied AI agent skills
✓ Copied base styles
✓ Created configuration files
✓ Git repository initialized

✨ Created UIGen project: my-admin-ui

📁 Project structure:
   ├── .git/
   ├── .gitignore
   ├── .agents/skills/
   ├── .uigen/
   │   ├── config.yaml
   │   ├── base-styles.css
   │   └── theme.css
   ├── openapi.yaml
   ├── annotations.json
   └── README.md

✓ Git repository initialized
✓ AI agent skills installed
✓ Base styles copied
✓ Configuration scaffolded

🚀 Next steps:

   cd my-admin-ui
   uigen serve openapi.yaml

Step 2: Start the development server

Navigate to your project and start the server:

cd my-admin-ui
npx @uigen-dev/cli serve openapi.yaml

The server will start at http://localhost:4400.

Optional: Desktop window

To open the same UI in an Electron window instead of the browser:

npx @uigen-dev/cli serve openapi.yaml --target electron

Install @uigen-dev/target-electron first if you are not in the UIGen monorepo. See Electron Target.

Step 3: Open the browser

Navigate to http://localhost:4400. UIGen serves a complete React SPA with:

  • A sidebar listing all resources detected from your spec
  • A dashboard overview with resource counts
  • Fully functional list, detail, create, edit, and delete views

Step 4: Navigate the generated UI

Click any resource in the sidebar to open its list view. From there you can:

  • Browse records fetched live from your API
  • Click a row to open the detail view
  • Use the New button to open the create form
  • Edit or delete records inline

Alternative: Quick test without init

If you just want to quickly test UIGen with an existing spec:

npx @uigen-dev/cli serve ./openapi.yaml

Or with a remote spec:

npx @uigen-dev/cli serve https://petstore3.swagger.io/api/v3/openapi.json

Customization

The fastest way to configure UIGen is using AI agents:

# Start the server
npx @uigen-dev/cli serve openapi.yaml

# Tell an AI agent what you want:
# "Hide password fields and mark email as required"
# "Product.categoryId is a foreign key to Category"  
# "Style with modern blue theme and dark mode"

# AI writes to .uigen/config.yaml and .uigen/theme.css
# Refresh browser to see changes

Visualize with Config GUI (Optional)

Open the config GUI to see what AI generated and make manual adjustments:

npx @uigen-dev/cli config openapi.yaml

Opens at http://localhost:4401 with tabs to visualize annotations, relationships, and styling.

Auto-annotate with AI

Use the included AI agent skill to automatically add UIGen annotations:

  1. Open your AI agent (Kiro, Claude, ChatGPT, etc.)
  2. Ask: "Use the auto-annotate skill to add UIGen annotations to my OpenAPI spec"
  3. The agent will read .agents/skills/auto-annotate.md and intelligently annotate your spec

Customize the theme

AI can generate themes, or edit .uigen/theme.css manually:

:root {
  --primary-color: #your-brand-color;
  --font-family: 'Your Font', sans-serif;
}

Custom options

Custom port

npx @uigen-dev/cli serve openapi.yaml --port 8080

Custom proxy base

If your API runs on a different host than what's declared in the spec's servers field:

npx @uigen-dev/cli serve openapi.yaml --proxy-base http://localhost:3001

Verbose logging

npx @uigen-dev/cli serve openapi.yaml --verbose

Hardware and IoT projects

For embedded examples (ESP32, STM32), run the device simulator from the example root, then start UIGen from the UI/ subdirectory so .uigen/config.yaml is picked up:

cd examples/apps/cpp/esp32-simulator/UI
npx @uigen-dev/cli serve openapi.yaml --proxy-base http://localhost:8080

See Example Apps for full setup instructions.

Next steps