SpecStar Web Generator

🚀 Code generator for SpecStar frontend applications. Automatically generates a complete React/TypeScript/Mantine web application from your SpecStar API's OpenAPI specification.

Features

• TypeScript Types: Auto-generated from OpenAPI schemas
• API Clients: Axios-based clients for all resources
• List Pages: Server-side pagination with Mantine React Table
• Detail Pages: View, edit, and revision history
• Create Pages: Auto-generated forms with validation
• Dashboard: Resource overview with counts
• TanStack Router: File-based routing

Installation

npm install -g specstar-web-generator
# or
pnpm add -g specstar-web-generator

Usage

Initialize a New Project

specstar-web init my-app
cd my-app
pnpm install

Generate Code from API

Make sure your SpecStar backend is running, then:

pnpm generate --url http://localhost:8000

Start Development Server

pnpm dev

Visit http://localhost:5173 to see your generated app.

CLI Commands

specstar-web init <project-name>

Initialize a new SpecStar Web project.

Options:

• -d, --dir <directory>: Target directory (default: current directory)

Example:

specstar-web init my-game-admin

specstar-web generate

Generate code from SpecStar API OpenAPI spec.

Options:

• -u, --url <api-url>: Backend API URL — used to fetch the OpenAPI spec and written to .env as the Vite dev proxy target (default: http://localhost:8000)
• -o, --output <directory>: Output directory (default: src)
• --openapi-path <path>: Path to OpenAPI spec endpoint (default: /openapi.json)
• --base-path <path>: API base path prefix, auto-detected if omitted

Example:

specstar-web generate --url http://localhost:8000
# With non-root API prefix:
specstar-web generate --url http://localhost:8000 --base-path /api/v1

After running, .env will contain:

VITE_API_URL=/api
API_PROXY_TARGET=http://localhost:8000

generate also resolves the app's branding — see below.

Branding

The generated app is your admin console, so it carries your name and logo. On every generate, the title and logo are resolved from the first source that is set:

1. title / logo in .specstarrc.json
2. the backend's OpenAPI info.title
3. SpecStar Admin and /specstar-mark.svg

// .specstarrc.json
{
  "mantineVersion": "8",
  "title": "Northwind Console",
  "logo": "/northwind.svg"
}

logo is a path served from public/, so /northwind.svg means public/northwind.svg.

The resolved values are written to src/specstar/generated/branding.ts (imported by the landing page and admin header) and stamped into index.html, which is where the browser reads the tab title and favicon before React boots.

Notes:

• A backend that never set a title reports the stock FastAPI, which is ignored so it cannot become your app's name.
• index.html is only rewritten if it already has a <title> / icon link, so integrate won't add tags to a project that dropped them.
• Re-run generate after editing .specstarrc.json.

specstar-web integrate

Integrate SpecStar generated code into an existing React project without overwriting your package.json, tsconfig, vite.config.ts, etc.

Options: same as generate.

specstar-web integrate --url http://localhost:8000

See INTEGRATION.md for a detailed step-by-step guide.

Generated Structure

my-app/
├── public/                      # Static assets
│   └── specstar-mark.svg        # Default logo / favicon
├── src/
│   ├── specstar/
│   │   ├── generated/           # Auto-generated (gitignored)
│   │   │   ├── types.ts         # TypeScript interfaces
│   │   │   ├── resources.ts     # Resource registry
│   │   │   ├── branding.ts      # APP_TITLE + APP_LOGO
│   │   │   └── api/
│   │   │       ├── characterApi.ts
│   │   │       ├── guildApi.ts
│   │   │       └── ...
│   │   ├── lib/                 # Template components (tracked)
│   │   │   ├── client.ts        # Axios instance
│   │   │   ├── resources.ts     # Resource config helpers
│   │   │   ├── components/      # Reusable UI components
│   │   │   ├── hooks/           # Custom React hooks
│   │   │   └── utils/           # Utility functions
│   │   └── types/               # Shared types (tracked)
│   │       └── api.ts
│   ├── routes/
│   │   ├── __root.tsx           # Root layout
│   │   ├── index.tsx            # Dashboard
│   │   ├── specstar-admin/
│   │   │   ├── character/
│   │   │   │   ├── index.tsx    # List page
│   │   │   │   ├── create.tsx   # Create page
│   │   │   │   └── $resourceId.tsx # Detail page
│   │   │   └── ...
│   │   └── ...
│   ├── App.tsx
│   └── main.tsx
├── package.json
└── vite.config.ts

Tech Stack

• React 19 + TypeScript
• Vite - Build tool
• Mantine 7 - UI components
• Mantine React Table - Data tables
• TanStack Router - File-based routing
• Axios - HTTP client

Development Workflow

1. Initialize: specstar-web init my-app
2. Install dependencies: pnpm install
3. Generate code: pnpm generate --url http://your-api:8000
4. Start dev server: pnpm dev
5. Make API changes → Re-run pnpm generate

Requirements

• Node.js >= 18.0.0
• SpecStar backend with OpenAPI spec at /openapi.json

API Proxy & Environment Variables

The generated app uses a Vite dev server proxy to avoid CORS issues during development.

How It Works

| Environment | VITE_API_URL | Request Path | Actual Target | |-------------|----------------|-------------|---------------| | Dev | /api (default) | /api/character → Vite proxy | http://localhost:8000/character | | Prod | http://server:port | http://server:port/character | Direct to backend |

All API requests go through the Axios client in src/lib/client.ts, which reads VITE_API_URL as its base URL.

In dev mode, requests to /api/* are intercepted by the Vite dev server and forwarded to the backend (with the /api prefix stripped). This means no CORS configuration is needed on the backend for development.

Environment Variables

The generator writes a .env file (git-ignored) with these variables:

| Variable | Scope | Default | Description | |----------|-------|---------|-------------| | VITE_API_URL | Browser (runtime) | /api | Base URL for Axios requests. Use /api for dev (proxy), or a full URL for prod. | | API_PROXY_TARGET | Vite dev server only | http://localhost:8000 | Backend URL that /api requests are proxied to. Not exposed to the browser. |

See .env.example for reference.

Development (Default)

No extra config needed — just start the backend and the dev server:

# Terminal 1: Start your SpecStar backend
uv run python examples/rpg_game_api.py

# Terminal 2: Start the frontend dev server
cd app && pnpm dev

The Vite dev server will proxy /api/* → http://localhost:8000/*.

If your backend runs on a different host or port, edit .env:

API_PROXY_TARGET=http://192.168.1.100:9000

Production

For production builds, set VITE_API_URL to the actual backend URL:

VITE_API_URL=http://your-server:8000

Then build:

pnpm build

The proxy is only active during pnpm dev — production builds use VITE_API_URL directly.

CORS (Optional)

With the dev proxy, you generally don't need CORS on the backend. However, if you prefer direct browser-to-backend requests (e.g., set VITE_API_URL=http://localhost:8000 without proxy), configure CORS:

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:5173"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

License

MIT

Gallery