---

name: fullstack-app description: Guidance for building fullstack apps with Vite (React + TypeScript) frontend and FastAPI backend. Use when demos need a web UI beyond what Streamlit provides. allowed-tools: Read, Bash, Glob, Write, Edit

Fullstack App Development (Vite + FastAPI)

When to Use This vs Streamlit

Use Streamlit if:

• App is read-only (displaying charts/tables)
• User is you or colleagues (internal tool)
• State doesn't matter (page refresh resets inputs = fine)

Use Vite + FastAPI if:

• Need login/auth
• Need to save user data (CRUD)
• UI must feel responsive (Streamlit lags on every click)
• Showing to non-technical stakeholders (Shadcn looks polished)

---

Tech Stack

Layer	Technology
Frontend	Vite + React + TypeScript
Styling	Tailwind CSS + Shadcn UI
Backend	FastAPI (Python)
Package Manager	pnpm
The Glue	OpenAPI (FastAPI auto-generates it)

---

Project Setup

1. Initialize Structure

mkdir my-app && cd my-app

# Frontend
pnpm create vite@latest frontend --template react-ts
cd frontend
pnpm install

# Add Tailwind v4 (uses Vite plugin, NOT tailwind.config.js)
pnpm add tailwindcss @tailwindcss/vite
# Replace src/index.css contents with: @import "tailwindcss";

# Initialize Shadcn (use explicit flags to avoid interactive prompts)
pnpm dlx shadcn@latest init -y --base-color neutral

cd ..

# Backend
mkdir backend
cd backend
uv init
uv add fastapi uvicorn pydantic

2. Configure vite.config.ts (Tailwind v4)

IMPORTANT: Tailwind v4 uses a Vite plugin. Do NOT create a tailwind.config.js file.

// frontend/vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import path from 'path'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
})

3. Configure CORS (backend/main.py)

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

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

Alternative: Vite Proxy (avoids CORS entirely)

Instead of CORS middleware, you can proxy API requests through Vite. Add to vite.config.ts:

server: {
  proxy: {
    '/api': {
      target: 'http://localhost:8000',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, ''),
    },
  },
},

Then use /api/analyze instead of http://localhost:8000/analyze in your frontend fetch calls.

---

The OpenAPI Workflow (Critical)

The biggest risk: Frontend guessing what backend built.

The solution: Use FastAPI's auto-generated OpenAPI spec as the contract.

Workflow:

1. Build backend first with proper Pydantic models
2. Run backend: uv run uvicorn main:app --reload
3. Check the contract: Visit http://localhost:8000/openapi.json
4. Build frontend against the contract - Reference the spec, don't guess

Frontend Typing Pattern

// Define types matching your Pydantic models
interface AnalyzeRequest {
  text: string;
}

interface AnalyzeResponse {
  score: number;
  explanation: string;
}

// Type-safe fetch
async function analyzeText(data: AnalyzeRequest): Promise<AnalyzeResponse> {
  const res = await fetch('http://localhost:8000/analyze', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data),
  });
  return res.json();
}

---

Shadcn UI Rules

Critical: Shadcn components must be installed before use.

# Correct - install first
pnpm dlx shadcn@latest add button
# Then import
import { Button } from "@/components/ui/button"

# WRONG - this package doesn't exist
import { Button } from "shadcn-ui"

Common components to install:

pnpm dlx shadcn@latest add button card input form dialog

Project structure:

• /components/ui/ - Shadcn base components (CLI puts them here)
• /components/features/ - Your composed components using Shadcn

---

Architecture Rules

Frontend = Display Only

• No complex data manipulation in JS
• Use React.useState for UI toggles
• Use React.useEffect for data fetching
• Keep business logic in Python

Backend = Logic & State

• All heavy lifting in Python
• Use Pydantic models for ALL request/response bodies
• This ensures frontend gets correct types

---

Running the App

# Terminal 1: Backend
cd backend
uv run uvicorn main:app --reload --port 8000

# Terminal 2: Frontend
cd frontend
pnpm run dev
# Opens at http://localhost:5173

---

Leveling Up (For Complex Apps)

For simple demos (1-2 endpoints), the patterns above are sufficient.

For more complex apps:

Need	Tool
Auto-generate TypeScript client	npx @hey-api/openapi-ts -i http://localhost:8000/openapi.json -o src/client
Caching, loading states, refetching	TanStack Query (React Query)

These add complexity - only use if the demo genuinely needs them.