Home

Next.js FastAPI Template¶

Next.js + FastAPI Template: Modern stack with Python and TypeScript, validation with Zod.

Documentation: https://jonasotoaguilar.github.io/nextjs-fastapi-template/

Source Code: https://github.com/jonasotoaguilar/nextjs-fastapi-template/

Original Template: Vinta Software - Next.js FastAPI Template

This template provides a solid foundation for scalable and high-performance web applications, following clean architecture and best practices. It simplifies development by integrating FastAPI, Pydantic, and Next.js with TypeScript and Zod, ensuring end-to-end type safety and schema validation between frontend and backend.

The FastAPI backend supports fully asynchronous operations, optimizing database queries, API routes, and test execution for better performance. Deployment is simple, with both backend and frontend fully deployable on Vercel, allowing for quick launches with minimal configuration.

🚀 Quick Start¶

Prerequisites¶

Docker and Docker Compose (recommended)
Or:
Node.js 18+ and pnpm 10+
Python 3.12
PostgreSQL 15+

Quick Installation with Docker¶

# 1. Clone the repository
git clone https://github.com/jonasotoaguilar/nextjs-fastapi-template.git
cd nextjs-fastapi-template

# 2. Initialize environment variables
make init-env

# 3. Build and start services
make docker-build
make docker-up

# 4. Apply migrations
make docker-migrate-db

# 5. Open in browser
# Frontend: http://localhost:3000
# Backend API: http://localhost:8000
# API Docs: http://localhost:8000/docs

Installation without Docker¶

# 1. Clone the repository
git clone https://github.com/jonasotoaguilar/nextjs-fastapi-template.git
cd nextjs-fastapi-template

# 2. Initialize environment variables
make init-env

# 3. Install dependencies
make install

# 4. Configure PostgreSQL database
# Edit api/.env with your DATABASE_URL

# 5. Apply migrations
cd api && uv run alembic upgrade head

# 6. Start services (in separate terminals)
make start-api    # Terminal 1 - Backend on :8000
make start-ui     # Terminal 2 - Frontend on :3000

Key Features¶

✔ End-to-end type safety – Typed clients automatically generated from the OpenAPI schema ensure frictionless API contracts between frontend and backend.

✔ Hot-reload updates – The client updates automatically when backend routes change, keeping FastAPI and Next.js synchronized.

✔ Versatile foundation – Designed for MVPs and production-ready applications, with a pre-configured authentication system and API layer.

✔ Quick deployment – Deploy a full-stack application—including authentication flow—on Vercel in a few steps.

✔ Production-ready authentication – Includes a pre-configured authentication system, allowing you to start development immediately with user management features.

Tech Stack¶

This template includes a carefully selected set of technologies to ensure efficiency, scalability, and ease of use:

Zod + TypeScript – Type safety and schema validation across the stack.
fastapi-users – Complete authentication system with:
Secure password hashing
JWT authentication
Password recovery via email
shadcn/ui – Pre-built React components with Tailwind CSS.
@hey-api/openapi-ts – Fully typed client generation from the OpenAPI schema.
UV – Simplified dependency management and packaging.
Docker Compose – Consistent environments for development and production.
Pre-commit hooks – Automatic linting, formatting, and code validation before commits.
Vercel Deployment – Serverless backend and scalable frontend, deployable with minimal configuration.

This is a partial list of technologies included in the template. For a full description, visit our Technology Selection page.

Getting Started¶

To use this template, visit our Get Started guide and follow the steps.

Project Structure¶

nextjs-fastapi-template/
├── api                      # FastAPI Backend
│   ├── app/                 # Application code
│   │   ├── core/            # Core infrastructure (shared)
│   │   └── modules/         # Domain-driven modules
│   ├── alembic_migrations/  # Database migrations
│   ├── commands/            # Utility scripts
│   └── tests/               # Backend tests (Core & Modules)
├── ui/                      # Next.js Frontend
│   ├── app/                 # Routes & Server Actions
│   ├── components/          # UI Components
│   ├── lib/                 # Config, Utilities & API Client
│   └── public/              # Static assets
├── docs/                    # MkDocs Documentation
└── docker-compose.yml       # Docker configuration

📚 Specific Documentation¶

For detailed information about each part of the project:

Frontend (UI) - Full Next.js frontend documentation
Component structure
Typed API client
Testing with Vitest
Configuration and deployment
Backend (API) - Full FastAPI backend documentation
Available endpoints
Models and schemas
Database migrations
Testing with pytest

Extending the template¶

Adding new models¶

Define the model in the backend (api/app/modules/<module>/models.py):

from sqlalchemy import Column, String, Integer
from app.core.base import Base

class Product(Base):
    __tablename__ = "products"

    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, nullable=False)

Create Pydantic schemas (api/app/modules/<module>/schemas.py):

from pydantic import BaseModel

class ProductRead(BaseModel):
    id: int
    name: str

    model_config = {"from_attributes": True}

Create database migration:

make docker-db-schema migration_name="add products table"
make docker-migrate-db

Adding new endpoints¶

Create/Update router (api/app/modules/<module>/router.py):

from fastapi import APIRouter, Depends
from sqlalchemy.ext.asyncio import AsyncSession
from app.core.database import get_async_session
from .schemas import ProductRead

router = APIRouter(prefix="/products", tags=["products"])

@router.get("/", response_model=list[ProductRead])
async def get_products(
    session: AsyncSession = Depends(get_async_session)
):
    # Implementation
    pass

Register the router (api/app/main.py):

from app.modules.product.router import router as product_router

app.include_router(product_router)

Regenerate frontend client:

# Hot-reload does it automatically, or manually:
cd ui && pnpm run generate-client

Using the typed client in the frontend¶

import { authJwtLogin } from "@/lib/clientService";

// The client is fully typed and categorized by tags
const { data, error } = await authJwtLogin({
  body: {
    username: "user@example.com",
    password: "securepassword",
  },
});

if (data) {
  console.log(data.access_token);
}

Useful Commands¶

The project includes a Makefile with commands to simplify common tasks:

make help                    # See all available commands
make docker-build           # Build containers
make docker-start-api       # Start api
make docker-start-ui        # Start ui
make docker-migrate-db      # Apply migrations
make test-api               # Run api tests
make test-ui                # Run ui tests

Contributing¶

Are you using this template? We'd love to hear how you're using it!

Join the conversation on GitHub Discussions
Report bugs or suggest improvements via issues
Check the Contributing guide to get involved

Credits¶

This project is a fork of the original template created and maintained by Vinta Software. The original template is actively used in production systems they build for their clients.

Original Template: vintasoftware/nextjs-fastapi-template

Disclaimer: This project is not affiliated with Vercel.