nextjs-fastapi-template

Table of Contents

• About
• Local Setup
  • Installing Required Tools
  • Setting Up Environment Variables
  • If you are not using Docker
    • Backend
    • Frontend
  • If you are using Docker
• Pre-Commit Setup
• Running the Application
• Watchers
  • Recommended Approach
  • Manual Execution of Watcher Commands
• Makefile
• Important Considerations

About

This template streamlines building APIs with FastAPI and dynamic frontends with Next.js. It integrates the backend and frontend using @hey-api/openapi-ts to generate a type-safe client, with automated watchers to keep the OpenAPI schema and client updated, ensuring a smooth and synchronized development workflow.

• Next.js: Fast, SEO-friendly frontend framework
• FastAPI: High-performance Python backend
• Zod + TypeScript: End-to-end type safety and schema validation
• fastapi-users: Built-in authentication and user management
• OpenAPI-fetch: Fully typed client generation from OpenAPI schema
• Watchers:
  • Backend: Watchdog for monitoring file changes
  • Frontend: Chokidar for live updates
• Docker: Consistent environments for development and production
• Pre-commit hooks: Enforce code quality with automated checks
• OpenAPI JSON schema: Centralized API documentation and client generation

With this setup, you’ll save time and maintain a seamless connection between your backend and frontend, boosting productivity and reliability.

Local Setup

Installing Required Tools

1. Poetry

Poetry is used to manage Python dependencies in the backend. Install Poetry by following the official installation guide.

Once installed, navigate to the fastapi_backend directory and run:

poetry install

2. Node.js and npm

Ensure Node.js and npm are installed for running the frontend. Follow the Node.js installation guide.

Install the frontend dependencies by navigating to the nextjs-frontend directory and running:

npm install

3. Docker

Docker is needed to run the project in a containerized environment. Follow the appropriate installation guide:

• Install Docker for Mac
• Install Docker for Windows
• Get Docker CE for Linux

4. Docker Compose

Ensure docker-compose is installed. Refer to the Docker Compose installation guide.

Setting Up Environment Variables

Create or update the .env files in the fastapi_backend and nextjs-frontend directories with the following variables:

Backend (fastapi_backend/.env):

For local setup:

DATABASE_URL=postgresql+asyncpg://postgres:password@localhost:5432/mydatabase

For Docker setup, replace localhost with db:

DATABASE_URL=postgresql+asyncpg://postgres:password@db:5432/mydatabase

Other environment variables remain unchanged:

ACCESS_SECRET_KEY=<your-secret-key>
RESET_PASSWORD_SECRET_KEY=<your-secret-key>
VERIFICATION_SECRET_KEY=<your-secret-key>
OPENAPI_OUTPUT_FILE=../nextjs-frontend/openapi.json

MAIL_USERNAME=<your-username>
MAIL_PASSWORD=<your-password>
MAIL_FROM=<your-from>
MAIL_SERVER=<your-server>

Frontend (nextjs-frontend/.env.local):

NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
OPENAPI_OUTPUT_FILE=openapi.json

If you are not using Docker:

To run the project locally, use the following commands:

Backend

1. Navigate to the fastapi_backend directory.
2. Use Docker to run the database to avoid local installation issues. Build and start the database container:

   docker compose build db
   docker compose up db

3. Run the following command to apply database migrations:

   make docker-migrate-db

4. Start the FastAPI server:

   make start-backend

Frontend

1. Navigate to the nextjs-frontend directory.
2. Install dependencies (if not already installed):

   npm install

3. Start the Next.js development server:

   make start-frontend

If you are using Docker:

1. Ensure Docker is running.

2. Run the following command to build and start the backend, frontend, and database containers:

   make docker-up-backend
   make docker-up-frontend

   This command will automatically set up the database and other necessary containers.

3. To create the database schema for the first time, run:

   make docker-migrate-db

Pre-Commit Setup

To maintain code quality and consistency, the project includes two separate pre-commit configuration files:

• .pre-commit-config.yaml for running pre-commit checks locally.
• .pre-commit-config.docker.yaml for running pre-commit checks within Docker.

Installing and Activating Pre-Commit Hooks

To activate pre-commit hooks, run the following commands for each configuration file:

• For the local configuration file:

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

• For the Docker configuration file:

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

Running Pre-Commit Checks

To manually run the pre-commit checks on all files, use:

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

or

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

Updating Pre-Commit Hooks

To update the hooks to their latest versions, run:

pre-commit autoupdate

Running the Application

• Backend: Access the API at http://localhost:8000.
• Frontend: Access the web application at http://localhost:3000.

Watchers

The project includes two watchers, one for the backend and one for the frontend, which automatically restart when they detect changes.

• The backend watcher monitors changes to the API code.
• The frontend watcher monitors changes to the openapi.json schema generated by the backend.

Recommended Approach: Run Both Watchers and Servers Simultaneously

To streamline development, it is recommended to run both the backend and frontend watchers at the same time. This approach will start both servers and their respective watchers, ensuring they are restarted automatically whenever changes are detected.

• Use the following commands:

  make watch-backend
  make watch-frontend

This will run both the backend and frontend servers, as well as the watchers, ensuring that the application is always up-to-date without needing manual restarts.

Manual Execution of Watcher Commands

You can manually execute the same commands that the watchers call when they detect a change:

1. To export the openapi.json schema:

   cd fastapi_backend && poetry run python -m app.commands.generate_openapi_schema

   or using Docker:

   docker compose run --rm --no-deps -T backend poetry run python -m app.commands.generate_openapi_schema

2. To generate the frontend client:

   cd nextjs-frontend && npm run generate-client

   or using Docker:

   docker compose run --rm --no-deps -T frontend npm run generate-client

Makefile

This project includes a Makefile that provides a set of commands to simplify common tasks such as starting the backend and frontend servers, running tests, building Docker containers, and more.

Available Commands

You can see all available commands and their descriptions by running the following command in your terminal:

make help

Important Considerations

• Environment Variables: Ensure your .env files are up-to-date.
• Database Setup: It is recommended to use Docker for running the database, even when running the backend and frontend locally, to simplify configuration and avoid potential conflicts.
• Consistency: It is not recommended to switch between running the project locally and using Docker, as this may cause permission issues or unexpected problems. Choose one method and stick with it.