nextjs-fastapi-template

Table of Contents

• About
• Production-Ready Authentication & Dashboard
• Getting Started with This Template
• Setup
  • Installing Required Tools
    • 1. Poetry
    • 2. Node.js, npm and pnpm
    • 3. Docker
    • 4. Docker Compose
  • Setting Up Environment Variables
  • Running the Database
  • Build the project (without Docker)
    • Backend
    • Frontend
  • Build the project (with Docker)
    • Backend
    • Frontend
• Running the Application
• Hot Reload on development
  • Manual Execution of Hot Reload Commands
• Testing
• Email Localhost Setup
• Pre-Commit Setup
  • Installing and Activating Pre-Commit Hooks
  • Running Pre-Commit Checks
  • Updating Pre-Commit Hooks
• Alembic Database Migrations
• GitHub Actions
  • Secrets Configuration
• Makefile
• Important Considerations
• Contributing
• Share your project!
• Commercial Support

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
• SQLAlchemy: Powerful Python SQL toolkit and ORM
• PostgreSQL: Advanced open-source relational database
• Pydantic: Data validation and settings management using Python type annotations
• Zod + TypeScript: End-to-end type safety and schema validation
• fastapi-users: Complete authentication system with:
  • Secure password hashing by default
  • JWT (JSON Web Token) authentication
  • Email-based password recovery
• Shadcn/ui: Beautiful and customizable React components
• OpenAPI-fetch: Fully typed client generation from OpenAPI schema
• fastapi-mail: Efficient email handling for FastAPI applications
• Poetry: Dependency management and packaging made easy
• Pytest: Powerful Python testing framework
• Code Quality Tools:
  • Ruff: Fast Python linter
  • ESLint: JavaScript/TypeScript code quality
• Hot reload watchers:
  • Backend: Watchdog for monitoring file changes
  • Frontend: Chokidar for live updates
• Docker and Docker Compose: Consistent environments for development and production
• MailHog: Email server for development
• 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.

Production-Ready Authentication & Dashboard features

This template comes with a pre-configured authentication system and a simple dashboard interface, allowing you to start building your application with user management features right away.

Getting Started with This Template

To use this template for your own project:

1. Create a new repository using this template by following GitHub's template repository guide
2. Clone your new repository and navigate to it: cd your-project-name
3. Update this README:
   • Change the project name in the first line
   • Remove this "Getting Started with This Template" section
4. Make sure you have Python 3.12 installed

Once completed, proceed to the Setup section below.

Setup

Installing Required Tools

1. Poetry

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

2. Node.jsm, npm and pnpm

Ensure Node.js and npm are installed for running the frontend. Follow the Node.js installation guide. After that install pnpm by running:

npm install -g pnpm

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

Backend (fastapi_backend/.env): Copy the .env.example files to .env and update the variables with your own values.

cd fastapi_backend && cp .env.example .env

1. You will only need to update the secret keys. You can use the following command to generate a new secret key:

   python3 -c "import secrets; print(secrets.token_hex(32))"

2. The DATABASE, MAIL, OPENAPI, CORS, and FRONTEND_URL settings are ready to use locally.
3. You can check the .env.example file for more information about the variables.

Frontend (nextjs-frontend/.env.local): Copy the .env.example files to .env. These values are unlikely to change, so you can leave them as they are.

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

Running the Database

1. 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

2. Run the following command to apply database migrations:

   make docker-migrate-db

Build the project (without Docker):

To setup the project environment locally, use the following commands:

Backend

1. Navigate to the fastapi_backend directory and run:

   poetry install

Frontend

1. Navigate to the nextjs-frontend directory and run:

   pnpm install

Build the project (with Docker):

1. Build the backend and frontend containers:

   make docker-build-backend
   make docker-build-frontend

Running the Application

If you are not using Docker:

1. Start the FastAPI server:

   make start-backend

2. Start the Next.js development server:

   make start-frontend

If you are using Docker:

1. Start the FastAPI server container:

   make docker-up-backend

2. Start the Next.js development server container:

   make docker-up-frontend

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

Hot Reload on development

The project includes two hot reloads when running the application, one for the backend and one for the frontend, which automatically restart local servers when they detect changes. This ensures that the application is always up-to-date without needing manual restarts.

• The backend hot reload monitors changes to the backend code.
• The frontend hot reload monitors changes to the frontend code, as well as to the openapi.json schema generated by the backend.

Manual Execution of Hot Reload Commands

You can manually execute the same commands that the hot reloads 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

Testing

To run the tests, you need to run the test database container:

make docker-up-test-db

Then run the tests locally:

make test-backend
make test-frontend

Or using Docker:

make docker-test-backend
make docker-test-frontend

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

Email Localhost Setup

To setup the email locally, you need to start MailHog by running the following command:

make docker-up-mailhog

• Email client: Access the email at http://localhost:8025.

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

Alembic Database Migrations

If you need to create a new Database Migration:

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

then apply the migration to the database:

make docker-migrate-db

GitHub Actions

This project comes with a pre-configured GitHub Actions setup to enable CI/CD. You can find the workflow configuration files inside the .github/workflows directory. Feel free to customize these workflows to better suit your project's needs.

Secrets Configuration

For the workflows to function correctly, make sure to add the necessary secret keys to your GitHub repository's settings. Navigate to Settings > Secrets and variables > Actions and add the following keys:

DATABASE_URL: The connection string for your primary database.
TEST_DATABASE_URL: The connection string for your test database.
ACCESS_SECRET_KEY: The secret key for access token generation.
RESET_PASSWORD_SECRET_KEY: The secret key for reset password functionality.
VERIFICATION_SECRET_KEY: The secret key for email or user verification.

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.

Contributing

If you wish to contribute to this project, please first discuss the change you wish to make via an issue.

Check our contributing guide to learn more about our development process and how you can test your changes to the boilerplate.

Share your project!

You can use our template to kick-start your project or streamline your efforts in securing funding. Starting with a strong foundation can make your product more resilient and allow you to focus on what matters most: delivering value to your customers.

If our template has been part of your journey, we'd love to hear about it! Share your story with us, and we’ll help spread the word about your project through our social media channels, giving it a broader reach.

Send us an email at [email protected] telling us a bit more about how our template helped you boost your project.

Commercial Support

This project is maintained by Vinta Software and is used in products of Vinta's clients. We are always looking for exciting work! If you need any commercial support, feel free to get in touch: [email protected]