@auto-engineer/react-gen

Generates a complete React application from a domain model by orchestrating a pipeline of AI agents that produce themed, routed, and validated code.

Purpose

Without @auto-engineer/react-gen, you would have to manually scaffold a React + Vite + Tailwind project, write every feature component by hand, configure routing, generate GraphQL typed operations, create a design theme, build a landing page, and run TypeScript/ESLint validation yourself -- for every domain model you produce.

Commands

| Command | Alias | Description | |---|---|---| | GenerateReactApp | build:frontend | Generate a complete React application from a domain model |

GenerateReactApp

Accepts a domain model (object or JSON file path) and a GraphQL schema, then runs a multi-stage AI pipeline to produce a fully functional React app in the specified output directory.

Fields:

| Field | Required | Description | |---|---|---| | outputDir | Yes | Output directory for the generated React app | | model | No | The domain model object (provide this or modelPath) | | modelPath | No | Path to the domain model JSON file (provide this or model) | | graphqlSchema | No | GraphQL schema string for the generated back end |

Events emitted:

| Event | Description | |---|---| | ReactAppGenerated | Front end built successfully. Payload: outputDir, sceneCount, sliceCount | | ReactAppGenerationFailed | Front end build failed. Payload: error, outputDir |

Example:

auto build:frontend --model-path=./model.json --output-dir=./client

Key Concepts

Domain Model -- A JSON structure containing scenes, each with moments. Scenes map to feature directories and routes. Moments map to React components. Validated with Zod against modelSchema.

Scene -- A top-level feature area (e.g., "Manage Bookings"). Gets its own route (/manage-bookings), feature directory (src/features/manage-bookings/), and page component.

Moment -- A unit of functionality within a scene. Types: command (mutation), query, experience (UI), react (server-only). Each moment with a request field gets a pre-generated typed GraphQL operation.

Pipeline -- The sequential/parallel execution of AI agents that together produce the full application. See Architecture.

Skills -- Bundled markdown instruction sets (in skills/) that are loaded into agent context at runtime. They encode design rules, component guidelines, and quality constraints that agents must follow.

Installation

pnpm add @auto-engineer/react-gen

Environment Variables

The package uses an OpenAI-compatible LLM provider. Set these before running:

CUSTOM_PROVIDER_NAME=       # Provider name
CUSTOM_PROVIDER_BASE_URL=   # API base URL
CUSTOM_PROVIDER_API_KEY=    # API key
CUSTOM_PROVIDER_DEFAULT_MODEL=  # Model identifier

Quick Start

Via message bus (programmatic)

import { generateReactAppCommandHandler } from '@auto-engineer/react-gen';

const event = await generateReactAppCommandHandler.handle({
  type: 'GenerateReactApp',
  data: {
    modelPath: './model.json',
    graphqlSchema: schemaString,
    outputDir: './output',
  },
  requestId: 'req-1',
  correlationId: 'cor-1',
  timestamp: new Date(),
});

if (event.type === 'ReactAppGenerated') {
  console.log(`Generated ${event.data.sceneCount} scenes`);
}

Via the generate script

MODEL_PATH=./model.json SCHEMA_PATH=./schema.graphql OUTPUT_DIR=./output pnpm generate

How-to Guides

Provide a domain model as an object

Instead of pointing to a JSON file, pass the model directly:

import { generateReactAppCommandHandler } from '@auto-engineer/react-gen';
import type { GenerateReactAppCommand } from '@auto-engineer/react-gen';

const model = {
  variant: 'app',
  scenes: [
    {
      name: 'Dashboard',
      id: 'dashboard',
      description: 'Main analytics dashboard',
      moments: [
        {
          type: 'query',
          name: 'View Stats',
          id: 'view-stats',
          request: 'query ViewStats { stats { total active } }',
        },
      ],
    },
  ],
};

await generateReactAppCommandHandler.handle({
  type: 'GenerateReactApp',
  data: { model, graphqlSchema: '...', outputDir: './out' },
  requestId: 'r1',
  correlationId: 'c1',
  timestamp: new Date(),
});

Customize the output stack

The generated app uses a starter template (bundled in starter/) that includes:

• Vite + React + TypeScript
• Tailwind CSS v4 with @theme inline
• shadcn/ui components (pre-installed in src/components/ui/)
• @tanstack/react-query for data fetching
• graphql-codegen for typed operations
• react-hook-form + Zod for forms
• lucide-react for icons
• sonner for toast notifications
• @dnd-kit for drag-and-drop

API Reference

Exports

// Command handler (registered via COMMANDS array)
export const generateReactAppCommandHandler: CommandHandler;

// COMMANDS array for auto-registration with the message bus
export const COMMANDS: CommandHandler[];

// Types
export type GenerateReactAppCommand;
export type GenerateReactAppEvents;
export type ReactAppGeneratedEvent;
export type ReactAppGenerationFailedEvent;

Domain Model Schema

import { modelSchema } from '@auto-engineer/react-gen'; // via types.ts

// Top-level
{ variant?: string; scenes: Scene[] }

// Scene
{ name: string; id?: string; description?: string; moments: Moment[] }

// Moment
{
  type: 'command' | 'query' | 'experience' | 'react';
  name: string;
  id: string;
  description?: string;
  request?: string;          // GraphQL operation string
  client?: { specs: ClientSpecNode[] };
  server?: { description?: string; specs?: GherkinSpec[]; data?: DataConfig };
  mappings?: Mapping[];
}

Architecture

The pipeline runs in three phases:

graph TD
    CMD[GenerateReactApp command] --> SCAFFOLD[1. Scaffold]
    SCAFFOLD --> CONSTANTS[2. Constants]
    CONSTANTS --> PAR1[3. Parallel generation]

    subgraph "Phase 3 — Parallel"
        PAR1 --> CODEGEN[Codegen agent]
        PAR1 --> LANDING[Landing page agent]
        PAR1 --> THEME[Theme agent]
        PAR1 --> SCENE1[Scene agent 1]
        PAR1 --> SCENEN[Scene agent N]
    end

    CODEGEN --> PAR2[4. Parallel validation]
    LANDING --> PAR2
    THEME --> PAR2
    SCENE1 --> PAR2
    SCENEN --> PAR2

    subgraph "Phase 4 — Parallel"
        PAR2 --> ROUTER[Router agent]
        PAR2 --> VALID[Validation agent]
    end

Pipeline stages

| Stage | Agent | What it does | |---|---|---| | 1 | Scaffold | Copies the starter template to outputDir, runs pnpm install | | 2 | Constants | Generates queries.ts / mutations.ts per feature from the model's request fields | | 3a | Codegen | Runs graphql-codegen to produce typed operations in src/gql/ | | 3b | Theme | AI agent writes src/index.css with domain-appropriate oklch colors, Outfit font, Tailwind v4 theme | | 3c | Landing page | AI agent writes src/components/landing-page.tsx with hero, feature cards, and CTAs | | 3d | Scene (per scene) | AI agent writes all component files for a scene plus its page component | | 4a | Router | AI agent writes App.tsx routing config connecting all scenes | | 4b | Validation | AI agent runs tsc and eslint, fixes errors in a loop until both pass |

Agent tooling

Each AI agent is equipped with a subset of these tools:

| Tool | Purpose | |---|---| | write_file | Write files to the output project (with protected-path enforcement) | | read_file | Read files from the output project | | list_files | List files in the output directory tree | | load_skills | Load design/quality skill instructions into agent context | | check_theme | Validate the generated index.css against theme requirements | | check_imports | Scan for banned patterns (direct graphql-request usage, missing landing page, banned fonts) | | run_tsc | Run TypeScript compiler, return errors | | run_eslint | Run ESLint, return errors | | exit_loop | Signal the agent loop to stop |

Protected files

Scene agents cannot overwrite these paths (theme/router/validation agents can):

• src/main.tsx, src/index.tsx, src/index.css, src/App.tsx
• src/lib/*, src/components/ui/*, src/gql/*
• src/features/*/queries.ts, src/features/*/mutations.ts