UIGen

Build & Run Declarative UI Apps. OpenAPI is your foundation.

---

Getting Started

Quick Start

# Initialize a new UIGen project
npx @uigen-dev/cli@latest init my-app

# Navigate to your project
cd my-app

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

Visit http://localhost:4400 to see your app.

UIGen scaffolds a complete project with configuration files (.uigen/config.yaml, .uigen/theme.css), AI agent skills (.agents/skills/), and an example spec if needed. The serve command renders a complete UI from your OpenAPI spec at runtime. When your API changes, the UI updates automatically with no regeneration or code maintenance required.

---

Key Features

Authentication & Authorization

• OAuth 2.0 Social Login - Google, GitHub, Facebook, Microsoft with automatic flow handling
• Bearer Token, API Key, HTTP Basic - All standard auth schemes supported
• Credential-based Login - Auto-detected from spec with token extraction
• Environment Variable Support - Secure credential management with ${VAR_NAME} syntax

Data Visualization & Forms

• Smart Forms - Auto-generated with validation, file uploads, nested objects, arrays
• DateTime Formatting - Declarative format patterns with timezone support
• File Uploads - Type-aware validation, previews, drag-and-drop (images, documents, videos)
• Chart Annotations - Line, bar, pie, scatter charts from array data
• Icon Library Support - Professional icons from Lucide, Heroicons, React Icons with library:iconName syntax

Relationships & Navigation

• Auto-detected Relationships - hasMany, belongsTo, manyToMany from path patterns
• Landing Pages - Hero, features, pricing, testimonials, FAQ sections
• Layout System - Sidebar, centered, dashboard-grid layouts per resource
• Profile Editing - Inline editing with validation and conflict handling

Developer Experience

• Runtime Rendering - No code generation, UI stays in sync with spec changes
• AI Agent Skills - Automate configuration with your favorite coding assistant
• Override System - Replace any view with custom React components (file-based or programmatic)
• Build Command - Package for production deployment with uigen build

---

Configuration

AI-Powered Configuration

Use AI agent skills with your favorite coding assistant (Cursor, Windsurf, Cline, etc.):

Ask your AI: "Use the auto-annotate skill to configure my OpenAPI spec"
Ask your AI: "Use the applying-styles skill to create a modern dark theme"
Ask your AI: "Use the configure-oauth skill to set up social login"

Skills are located in .agents/skills/ and automate pattern detection, annotation generation, OAuth setup, and styling.

Environment Variables: Keep sensitive values like OAuth credentials secure by using ${ENV_VAR_NAME} syntax in your config file. UIGen automatically loads .env files from your spec directory. See the Environment Variables Guide for details.

Try the Example App

git clone https://github.com/darula-hpp/uigen
cd uigen/examples/apps/fastapi/meeting-minutes

# Setup backend (FastAPI + PostgreSQL)
docker compose up -d
docker compose exec app alembic upgrade head

# Initialize and start
npx @uigen-dev/cli@latest init --spec openapi.yaml
npx @uigen-dev/cli@latest serve openapi.yaml --proxy-base http://localhost:8000

Visit http://localhost:4400 to explore a full meeting minutes application with CRUD operations, authentication, file uploads, and relationships.

---

AI Agent Skills

UIGen includes AI agent skills that automate configuration through intelligent analysis of your OpenAPI spec.

Available Skills

Auto-Annotate (auto-annotate.md)

• Detects auth endpoints (login, signup, password reset)
• Configures file uploads (types, size limits)
• Links relationships (foreign keys to resources)
• Hides internal endpoints (debug, health checks)
• Adds chart visualizations for array data
• Applies smart labels (technical names to human-readable)

Configure OAuth (configure-oauth.md)

• Sets up OAuth 2.0 social login (Google, GitHub, Facebook, Microsoft)
• Configures client IDs, redirect URIs, and scopes
• Generates environment variable placeholders
• Provides provider-specific setup instructions

Applying Styles (applying-styles-to-react-spa.md)

• Brand colors and dark mode support
• Component styling (buttons, forms, tables, cards)
• Animations and transitions
• Responsive design (mobile, tablet, desktop)

Configure Icons (configure-icons.md)

• Professional icon library integration (Lucide, Heroicons, React Icons)
• Icon reference format and usage examples
• Landing page and feature section icons
• Best practices and troubleshooting

Usage

Skills work with any AI coding assistant that can read files:

• Cursor: Reference with @.agents/skills/auto-annotate.md
• Windsurf: Ask "Use the auto-annotate skill"
• Cline: Provide skill file path in context
• GitHub Copilot Chat: Reference skill files in prompts

Example workflow:

npx @uigen-dev/cli@latest init my-app --spec openapi.yaml
# Ask AI: "Use the auto-annotate skill to configure my spec"
# Ask AI: "Use the configure-oauth skill to add Google login"
# Ask AI: "Use the configure-icons skill to add professional icons"
# Ask AI: "Use the applying-styles skill to create a professional theme"
npx @uigen-dev/cli@latest serve openapi.yaml

---

How It Works

UIGen uses runtime rendering to transform your OpenAPI spec into a complete, interactive frontend. Unlike code generators, UIGen interprets your spec at runtime, keeping your UI automatically in sync with API changes.

CLI Command
    |
    v
+----------------+     +----------------+     +----------+     +------+     +--------+     +--------------+
| API Document   |---->| Reconciler     |---->| Adapter  |---->|  IR  |---->| Engine |---->|  React SPA   |
| (YAML/JSON)    |     | (Config Merge) |     | (Parser) |     |      |     |        |     | (served)     |
+----------------+     +----------------+     +----------+     +------+     +--------+     +--------------+
       |                      ^                                                                    |
       |                      |                                                          +---------+
       |               +----------------+                                                v
       |               | Config File    |                                          +-----------+
       |               | (.uigen/       |                                          | API Proxy |---> Real API
       |               |  config.yaml)  |                                          +-----------+
       |               +----------------+
       |
       +---> (Source spec unchanged on disk)

UIGen reconciles your config with the spec, then parses it into a framework-agnostic Intermediate Representation (IR) containing resources, operations, schemas, authentication flows, and pagination strategies.

The React renderer interprets this IR at runtime and creates:

• Table views with sorting, filtering, pagination
• Create & edit forms with validation
• Detail views with related resource links
• Search interfaces from query parameters
• Authentication flows (Bearer, API Key, HTTP Basic, credential-based login)
• Multi-step wizards for complex forms
• Custom action buttons for non-CRUD endpoints
• Dashboard with resource overview
• Dark/light theme toggle

Key advantage: Runtime rendering means no regeneration step, no code to maintain, no drift between spec and UI. Because the IR is framework-agnostic, you can swap renderers. The same spec works with @uigen-dev/react, @uigen-dev/svelte, or @uigen-dev/vue (coming soon).

---

Override System

Customize any view while keeping the rest auto-generated. UIGen provides escape hatches at three levels:

Component Mode - Full control over data fetching and rendering:

// src/overrides/custom-profile.tsx
import type { OverrideDefinition } from '@uigen-dev/react';

function CustomProfile() {
  return <div>My Custom Profile View</div>;
}

const override: OverrideDefinition = {
  targetId: 'me',
  component: CustomProfile,
};

export default override;

Render Mode - UIGen fetches data, you control the UI:

// src/overrides/users-list.tsx
import type { OverrideDefinition, ListRenderProps } from '@uigen-dev/react';

const override: OverrideDefinition = {
  targetId: 'users.list',
  render: ({ data, isLoading }: ListRenderProps) => {
    if (isLoading) return <div>Loading...</div>;
    return <div className="grid">{/* your custom UI */}</div>;
  },
};

export default override;

UseHooks Mode - Side effects only (analytics, tracking):

// src/overrides/analytics.tsx
import { useEffect } from 'react';
import type { OverrideDefinition } from '@uigen-dev/react';

const override: OverrideDefinition = {
  targetId: 'users.list',
  useHooks: ({ resource }) => {
    useEffect(() => {
      analytics.track('page_view', { resource: resource.name });
    }, [resource]);
  },
};

export default override;

Add x-uigen-override annotation to .uigen/config.yaml:

annotations:
  GET:/api/v1/auth/me:
    x-uigen-override:
      id: me

The CLI automatically discovers, transpiles, and injects your overrides. See packages/react/src/overrides/README.md for complete documentation.

---

Read More

• Full Documentation - Complete guides, API reference, and examples
• Architecture - Deep dive into the IR, adapters, and rendering pipeline

---

Current Priorities

• Polish
• Stripe Integration
• Better relationship handling and visualization
• Additional renderers (Svelte, Vue)

---

License

MIT