---
name: initialize-fullstack
description: Initialize a fullstack repository with Vite React TypeScript frontend and Python FastAPI backend. Triggers on requests to create, scaffold, or bootstrap a new fullstack project, web application with API, or React + Python stack. Includes Docker configuration, shadcn/ui components, Tailwind CSS, and uv package management.
---

# Fullstack Project Initialization

Initialize a Vite + React + TypeScript frontend with a FastAPI Python backend, fully containerized.

## Quick Reference

| Component | Tool/Framework |
|-----------|----------------|
| Frontend | Vite, React, TypeScript, Tailwind, shadcn/ui |
| Backend | FastAPI, Python ≥3.12, uv package manager |
| Containers | Docker, docker-compose |

## Initialization Steps

### 1. Project Structure

Check current directory. If it contains existing project files, create a new directory with an appropriate name. Ensure `frontend/` and `backend/` directories exist.

Initialize git repository with `.gitignore` (leave empty for now).

### 2. Backend Setup

**Use `uv` for all Python package management.**

```bash
cd backend
uv init --python ">=3.12"
uv venv
uv add "fastapi[standard]"
```

Add `backend/.venv` to root `.gitignore`.

Update `pyproject.toml` with description and author if missing.

Create `.vscode/settings.json`:
```json
{
  "python.defaultInterpreterPath": "${workspaceFolder}/backend/.venv/bin/python",
  "python.terminal.activateEnvironment": true
}
```

### 3. Frontend Setup

```bash
cd frontend
npm create vite@latest . -- --template react-ts
npm install tailwindcss @tailwindcss/vite @types/node -D
```

**Configure Tailwind** — Replace `src/index.css`:
```css
@import "tailwindcss";
```

**Configure path aliases** — Add to `compilerOptions` in both `tsconfig.json` and `tsconfig.app.json`:
```json
"baseUrl": ".",
"paths": { "@/*": ["./src/*"] }
```

**Update `vite.config.ts`**:
```typescript
import path from "path"
import tailwindcss from "@tailwindcss/vite"
import react from "@vitejs/plugin-react"
import { defineConfig } from "vite"

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

**Initialize shadcn/ui**:
```bash
npx shadcn@latest init
npx shadcn@latest add button
```

**Apply theme** (default: twitter, or user's choice):
```bash
# Options: twitter | supabase
npx shadcn@latest add https://tweakcn.com/r/themes/twitter.json
```

### 4. Docker Configuration

**`backend/Dockerfile`** — Use `ghcr.io/astral-sh/uv:alpine` (or `uv:debian-slim` only if Debian packages required).

**`frontend/Dockerfile`** — Two-stage build: build with Node, serve with `node:slim` or nginx alpine.

**`docker-compose.yaml`** — Configure both services with appropriate ports and networking.

### 5. Sanity Check

Verify the stack works end-to-end:

1. **Backend**: Create `/ping` endpoint returning `{"message": "pong"}`
2. **Frontend**: Add a Button that calls `/ping` and displays the response
3. **Test**: Run `docker-compose up` and confirm the button works

## Theme Options

| Theme | Command |
|-------|---------|
| twitter (default) | `npx shadcn@latest add https://tweakcn.com/r/themes/twitter.json` |
| supabase | `npx shadcn@latest add https://tweakcn.com/r/themes/supabase.json` |