Next.js & FastAPI: een full-stack starter guide

Next.js en FastAPI zijn samen een krachtige combinatie: je krijgt de snelheid en developer experience van React met server-side rendering, gecombineerd met de performance en type-safety van een Python backend. Dit is exact de stack die ik gebruik voor mijn VorstersNV platform, en in dit artikel deel ik hoe je er zelf mee aan de slag gaat.

Waarom deze combinatie?

Next.js — React framework met SSR, routing, en geweldige DX
FastAPI — de snelste Python web framework met automatische OpenAPI docs
TypeScript + Python — type-safety aan beide kanten
Docker Compose — alles draait met één commando

Project structuur

Ik hanteer een monorepo structuur waarbij frontend en backend in dezelfde repository leven. Dit vereenvoudigt CI/CD, deployment en het beheer van gedeelde types:

text

project/
├── frontend/          # Next.js applicatie
│   ├── app/           # App Router pagina's
│   ├── components/    # Herbruikbare componenten
│   ├── data/          # Gedeelde data en types
│   └── package.json
├── api/               # FastAPI backend
│   ├── main.py        # Entry point
│   ├── routers/       # API endpoints per domein
│   └── auth/          # JWT authenticatie
├── db/                # Database modellen en migraties
├── docker-compose.yml # Complete stack definitie
└── Makefile           # Developer shortcuts

FastAPI backend opzetten

De backend begint simpel — een FastAPI app met CORS configuratie zodat de Next.js frontend erbij kan:

python

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI(title="MijnProject API", version="1.0.0")

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

@app.get("/api/health")
async def health():
    return {"status": "ok", "service": "api"}

Database met SQLAlchemy + Alembic

Voor de database gebruik ik PostgreSQL met SQLAlchemy als ORM en Alembic voor migraties. Dit geeft je versiebeheer voor je database schema — net zo belangrijk als Git voor je code:

python

from sqlalchemy import Column, Integer, String, DateTime
from sqlalchemy.ext.declarative import declarative_base
from datetime import datetime

Base = declarative_base()

class Project(Base):
    __tablename__ = "projecten"
    
    id = Column(Integer, primary_key=True)
    naam = Column(String(200), nullable=False)
    beschrijving = Column(String(2000))
    created_at = Column(DateTime, default=datetime.utcnow)

Next.js frontend met API calls

In de frontend gebruik ik de native fetch API om data op te halen van de backend. Met Next.js App Router kun je dit zowel server-side als client-side doen:

typescript

// app/projecten/page.tsx — Server Component
export default async function ProjectenPage() {
  const res = await fetch("http://localhost:8000/api/projecten", {
    cache: "no-store", // altijd verse data
  });
  const projecten = await res.json();

  return (
    <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
      {projecten.map((project: Project) => (
        <ProjectCard key={project.id} project={project} />
      ))}
    </div>
  );
}

Docker Compose: alles in één commando

Het mooie van deze stack is dat alles met Docker Compose draait. Database, backend, frontend, cache — één commando en alles staat klaar:

yaml

services:
  database:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: mijnproject
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data

  api:
    build: .
    ports:
      - "8000:8000"
    depends_on:
      - database

  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    depends_on:
      - api

Mijn ervaring

Deze stack draait nu in productie voor mijn eigen portfolio en platform. De combinatie van Python's kracht voor data-processing en AI, met de interactiviteit van React, is voor mij de sweet spot. FastAPI genereert automatisch OpenAPI docs, wat het debuggen en testen een stuk makkelijker maakt.

Start met een werkend skelet en bouw van daaruit op. Een docker-compose.yml met drie services en een Makefile met "make up" en "make down" — dat is alles wat je nodig hebt om productief te zijn.

Wil je de volledige broncode zien? Check mijn VorstersNV Platform project voor een werkend voorbeeld van deze stack in actie, inclusief Keycloak authenticatie, Redis caching, en AI-agent integratie.