DOCSEARCHbyAlgolia
Submit Docs

Next.js FastAPI Template

repository·main·Indexed 43 days ago

https://github.com/vintasoftware/nextjs-fastapi-template

A full-stack boilerplate combining a FastAPI (Python) backend with a Next.js (TypeScript) frontend. It features end-to-end type safety via OpenAPI, pre-configured authentication using fastapi-users, and optimized deployment for Vercel. The template includes a PostgreSQL database setup, Docker Compose for consistent environments, and automated client generation to keep the frontend and backend in sync.

Tokens
13K
Snippets
60
Records
80
Agent score
55%

What's inside Next.js FastAPI Template

  1. Overview of the Next.js FastAPI Template

    main

    The Next.js FastAPI Template is a full-stack foundation designed for building scalable, high-performance web applications. It integrates a Python backend (FastAPI) with a modern TypeScript frontend (Next.js), emphasizing clean architecture and end-to-end type safety.

    Key capabilities include:

    • End-to-end type safety: Uses OpenAPI schema to automatically generate typed clients, ensuring API contracts are respected between the frontend and backend.
    • Hot-reload synchronization: The client updates automatically when backend routes change, keeping the FastAPI and Next.js layers in sync.
    • Production-ready authentication: Includes a pre-configured system with user management, secure password hashing, JWT authentication, and email-based password recovery via fastapi-users.
    • Seamless Deployment: Optimized for Vercel, allowing both the frontend and the serverless backend to be deployed with minimal configuration.

  2. Understand the technology stack and integration workflow

    main

    This template provides a synchronized development workflow between a FastAPI backend and a Next.js frontend. The core integration mechanism uses @hey-api/openapi-ts to generate a type-safe client from the FastAPI-generated OpenAPI schema. This ensures that changes in the backend API are automatically reflected in the frontend types.

    Core Stack Components:

    • Backend: FastAPI (Python), SQLAlchemy (ORM), Pydantic (Validation), and PostgreSQL (Database).
    • Frontend: Next.js (React), Shadcn/ui (Components), and Zod/TypeScript (Validation/Typing).
    • Authentication: fastapi-users providing JWT, secure password hashing, and email-based recovery.
    • Package Management: uv for high-speed Python package management.
    • DevOps/Environment: Docker and Docker Compose for consistent environments, and MailHog for local email testing.

    Synchronization Workflow:

    1. Backend changes: Modifications to FastAPI routes or Pydantic models update the OpenAPI JSON schema.
    2. Client Generation: @hey-api/openapi-ts consumes the schema to generate a fully typed client.
    3. Frontend usage: The Next.js frontend uses the generated client (powered by openapi-fetch) to make type-safe API calls.

  3. Technology Stack and Core Dependencies

    main

    The template utilizes the following technologies to ensure efficiency and scalability:

    Frontend & Validation

    • Next.js: React framework for the frontend.
    • TypeScript & Zod: Provides type safety and schema validation across the entire stack.
    • shadcn/ui: Prebuilt React components styled with Tailwind CSS.
    • OpenAPI-fetch: Used for fully typed client generation from the backend's OpenAPI schema.

    Backend & Authentication

    • FastAPI: Asynchronous Python web framework.
    • fastapi-users: Manages the complete authentication system (JWT, password hashing, recovery).

    Tooling & Infrastructure

    • UV: Used for simplified Python dependency management and packaging.
    • Docker Compose: Ensures consistent development and production environments.
    • Pre-commit hooks: Automates linting, formatting, and validation.
    • Vercel: Target platform for serverless backend and scalable frontend deployment.

  5. Configure Frontend Project for GitHub Actions

    main

    To link the nextjs-frontend directory to Vercel for CI/CD, follow these steps:

    1. Navigate to the directory and link the project:

      cd nextjs-frontend
vercel link
      • Select No for "Link to existing project?"
      • Select No for "Modify settings?"

    2. Add Project IDs to GitHub Secrets: Open nextjs-frontend/.vercel/project.json and add these values to your GitHub repository secrets:

      • projectId $\rightarrow$ VERCEL_PROJECT_ID_FRONTEND
      • orgId $\rightarrow$ VERCEL_ORG_ID
    cd nextjs-frontend
vercel link

  6. Configure and run pre-commit hooks

    main

    The project uses pre-commit for code quality. There are two configurations available: .pre-commit-config.yaml (local) and .pre-commit-config.docker.yaml (Docker).

    Install Hooks

    To activate the hooks in your git workflow:

    Local configuration:

    pre-commit install -c .pre-commit-config.yaml

    Docker configuration:

    pre-commit install -c .pre-commit-config.docker.yaml

    Run Checks Manually

    To run checks against all files in the repository:

    Local:

    pre-commit run --all-files -c .pre-commit-config.yaml

    Docker:

    pre-commit run --all-files -c .pre-commit-config.docker.yaml

    Update Hooks

    To update all hooks to their latest versions:

    pre-commit autoupdate

  7. Manage Alembic database migrations

    main

    Use the following workflow to create and apply database schema changes.

    1. Create a new migration

    Provide a descriptive name for the migration using the migration_name argument:

    make docker-db-schema migration_name="add users"

    2. Apply the migration

    Run this command to update the database schema to the latest version:

    make docker-migrate-db
    make docker-db-schema migration_name="add users"

  8. Build the project locally (without Docker)

    main

    To run the components directly on your host machine:

    Backend

    Navigate to fastapi_backend and sync dependencies using uv:

    cd fastapi_backend
uv sync

    Frontend

    Navigate to nextjs-frontend and install dependencies using pnpm:

    cd nextjs-frontend
pnpm install
    cd fastapi_backend && uv sync
cd nextjs-frontend && pnpm install

  10. Install required tools for the template

    main

    To use this template, ensure the following tools are installed on your system:

    1. Python 3.12: Required for the backend.
    2. uv: Used to manage Python dependencies in the fastapi_backend directory. Follow the official installation guide.
    3. Node.js & npm: Required for the frontend.
    4. pnpm: Install globally via npm:
      npm install -g pnpm
    5. Docker & Docker Compose: Required for containerized environments and running the database.
    npm install -g pnpm

  11. Set up CI with GitHub Actions for Production

    main

    To enable continuous integration for production deployments, move the provided workflow files to your GitHub repository's workflow directory.

    Prerequisites

    1. Vercel Token: Generate a Vercel Access Token and add it to your GitHub repository secrets as VERCEL_TOKEN.
    2. Vercel CLI: Install it globally via pnpm and authenticate.

    Setup Steps

    1. Move workflow files:
      mv prod-backend-deploy.yml .github/workflows/prod-backend-deploy.yml
mv prod-frontend-deploy.yml .github/workflows/prod-frontend-deploy.yml
    2. Install and login to Vercel CLI:
      pnpm i -g vercel@latest
vercel login
    mv prod-backend-deploy.yml .github/workflows/prod-backend-deploy.yml
mv prod-frontend-deploy.yml .github/workflows/prod-frontend-deploy.yml

pnpm i -g vercel@latest
vercel login

  12. Configure environment variables for Backend and Frontend

    main

    The project uses environment files to manage configuration. You must copy the example files to the active .env files before running the application.

    Backend Configuration

    Navigate to fastapi_backend and copy the example file:

    cd fastapi_backend && cp .env.example .env

    Key Backend Settings:

    • Secret Keys: You must update the secret keys in .env. Generate a new 32-byte hex key using:
      python3 -c "import secrets; print(secrets.token_hex(32))"
    • DATABASE, MAIL, OPENAPI, CORS, FRONTEND_URL: These are pre-configured for local use. If using Docker, DATABASE and MAIL are handled by Docker Compose.
    • OPENAPI_URL: Uncomment this in .env to hide /docs and openapi.json (recommended for production).

    Frontend Configuration

    Navigate to nextjs-frontend and copy the example file:

    cd nextjs-frontend && cp .env.example .env.local

    Note: These values are typically standard and rarely need modification.

    cd fastapi_backend && cp .env.example .env
cd nextjs-frontend && cp .env.example .env.local