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