initialize-fullstack

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.

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:

{
  "python.defaultInterpreterPath": "${workspaceFolder}/backend/.venv/bin/python",
  "python.terminal.activateEnvironment": true
}

3. Frontend Setup

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

Configure Tailwind — Replace src/index.css:

@import "tailwindcss";

Configure path aliases — Add to compilerOptions in both tsconfig.json and tsconfig.app.json:

"baseUrl": ".",
"paths": { "@/*": ["./src/*"] }

Update vite.config.ts:

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:

npx shadcn@latest init
npx shadcn@latest add button

Apply theme (default: twitter, or user's choice):

# 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