Integrating React with FastAPI: A Production-Ready Guide

Having architected several full-stack applications combining FastAPI and React, I've learned that while both technologies are powerful on their own, combining them requires careful consideration of project structure, build processes, and deployment strategies. In this guide, I'll share my battle-tested approach to creating a production-ready FastAPI-React application.

Personal Experience Note: When I first integrated FastAPI with React, I struggled with development workflow and production builds. After deploying several applications serving millions of requests, I've developed a robust template that handles everything from hot reloading to production optimization.

Project Setup and Structure

The key to a successful FastAPI-React integration is a well-organized project structure. Here's the setup I've refined over multiple production deployments:

my_project/
├── backend/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py
│   │   ├── api/
│   │   │   ├── __init__.py
│   │   │   ├── endpoints/
│   │   │   └── dependencies.py
│   │   ├── core/
│   │   │   ├── config.py
│   │   │   └── security.py
│   │   └── services/
│   ├── requirements.txt
│   └── .env
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── services/
│   │   ├── hooks/
│   │   ├── utils/
│   │   ├── App.tsx
│   │   └── index.tsx
│   ├── package.json
│   └── vite.config.ts
└── docker-compose.yml

Initial Setup Guide

Step 1: Backend Setup

First, let's create a FastAPI backend that's optimized for serving a React application:

# backend/app/main.py
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from fastapi.staticfiles import StaticFiles

app = FastAPI(title="FastAPI React App")

# Configure CORS
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:5173"],  # Vite's default port
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# Mount React build directory in production
app.mount("/", StaticFiles(directory="../frontend/dist", html=True), name="static")

Step 2: Frontend Setup

For the frontend, I recommend using Vite for its superior development experience:

# Create React project with Vite
npm create vite@latest frontend -- --template react-ts

# Install essential dependencies
cd frontend
npm install @tanstack/react-query axios @mantine/core @mantine/hooks

Authentication Implementation

Here's a secure authentication setup I use in production:

# backend/app/core/security.py
from fastapi import Security, HTTPException
from fastapi.security import HTTPBearer
from jose import JWTError, jwt
from datetime import datetime, timedelta

security = HTTPBearer()

async def create_access_token(data: dict):
    to_encode = data.copy()
    expire = datetime.utcnow() + timedelta(minutes=15)
    to_encode.update({"exp": expire})
    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)

Common Questions and Solutions

Q: How do you handle API authentication in development vs production?

I use environment variables and different API configurations:

// frontend/src/config/api.ts
export const apiConfig = {
    baseUrl: import.meta.env.PROD 
        ? '/api' 
        : 'http://localhost:8000/api',
    timeout: 5000,
    withCredentials: true,
};

Q: What's the best way to handle form submissions?

I recommend using React Query with TypeScript for type-safe API calls:

export const useSubmitForm = () => {
    return useMutation({
        mutationFn: (data: FormData) => 
            api.post('/submit', data),
        onSuccess: () => {
            queryClient.invalidateQueries(['data'])
        },
    })
}

Deployment Strategy

For production deployment, I recommend this approach:

# backend/Dockerfile.prod
FROM python:3.11-slim

WORKDIR /app
COPY ./requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY ./app ./app
COPY ./frontend/dist ./static

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Conclusion

Creating a FastAPI-React template requires careful consideration of both development experience and production requirements. The setup I've shared here has proven reliable across multiple production deployments, handling everything from authentication to optimized builds.

Remember: The key to a successful FastAPI-React integration lies in proper project structure, efficient development workflow, and robust production optimization. Don't forget to implement proper error handling and type safety throughout your application.

Keep exploring the official documentation for both FastAPI and React as both technologies are rapidly evolving with new features and best practices.