FastAPI + React Template ·

           

This project serves as a template for bootstrapping a FastAPI and React project using a modern stack.

Features

• FastAPI (Python 3.8)
• React (with Typescript)
• PostgreSQL for the database
• SqlAlchemy for ORM
• Alembic for database migrations
• Pytest for backend tests
  • Includes test database, client, and user fixtures
• Prettier/ESLint (Airbnb style guide)
• Docker Compose for development
• Nginx as a reverse proxy to allow backend/frontend on the same port
• MaterialUI for styling
• react-admin for the admin dashboard
  • Using JWT authentication and login/redirects configured based on status codes
  • Only superusers are able to access the react-admin dashboard
• JWT authentication using OAuth2 and PyJWT

Background

This project is meant as a lightweight/React alternative to FastAPI's official fullstack project. If you want a more comprehensive project in Vue, I would suggest you start there.

Most of the boilerplate backend code is taken from that project or the FastAPI official docs. This is mainly setup to help with development, it has no opinions on how you should deploy your code.

Quick Start

First, install cookiecutter if you don't already have it:

pip install cookiecutter

Then, in the directory you want your project to live:

cookiecutter gh:Buuntu/fastapi-react

This will ask for the following variables to be set:

• project_name [default fastapi-react]
• project_slug [default fastapi-react]
• port [default 8000]
• postgres_user [default postgres]
• postgres_password [default password]
• postgres_database [default app]
• superuser_email [default [email protected]]
• superuser_password [default password]
• secret_key [default super_secret]

and will create a directory called whatever you set for project_slug.

Develop

Change into your project directory and run:

chmod +x scripts/build.sh
./scripts/build.sh

This will build and run the docker containers, run the alembic migrations, and load the initial data (a test user).

It may take a while to build the first time it's run since it needs to fetch all the docker images.

Once you've built the images once, you can simply use regular docker-compose commands to manage your development environment, for example to start your containers:

docker-compose up -d

Once this finishes you can navigate to the port set during setup (default is localhost:8000), you should see the slightly modified create-react-app page:

Note: If you see an Nginx error at first with a 502: Bad Gateway page, you may have to wait for webpack to build the development server (the nginx container builds much more quickly).

The backend docs will be at http://localhost:8000/api/docs.

Backend routes will be at http://localhost:8000/api.

Admin Dashboard

This project uses react-admin for a highly configurable admin dashboard.

After starting the project, navigate to http://localhost:8000/admin. You should see a login screen. Use the username/password you set for the superuser on project setup.

NOTE: regular users will not be able to access the admin dashboard

You should now see a list of users which you can edit, add, and delete. The table is configured with the REST endpoints to the FastAPI /users routes in the backend.

The admin dashboard is kept in the frontend/src/admin directory to keep it separate from the regular frontend.

Security

To generate a secure key used for encrypting/decrypting the JSON Web Tokens, you can run this command:

openssl rand -hex 32

The default is fine for development but you will want something more secure for production.

You can either set this on project setup as secret_key or manually edit the Python SECRET_KEY variable in backend/app/core/security.py.

Testing

This project comes with Pytest and a few Pytest fixtures for easier mocking. The fixtures are all located in backend/conftest.py within your project directory.

To use the test client, simply create a Pytest file and include test_db as an argument to your test method:

def test_user(test_db):
    # This is an empty test database and an instance of a SQLAlchemy Session class
    assert test_db.query(models.User).all()

To use an unauthenticated test client, use client:

def test_get_users(client):
    test_client.get("/api/v1/users")
    assert response.status_code == 200

Or if you need an authenticated client using OAuth2 and JWTs:

def test_user_me(client, user_token_headers):
    response = client.get(
      "/api/v1/users/me",
      headers=user_token_headers,
    )
    assert response.status_code == 200

Since OAuth2 expects the access token in the headers, you will need to pass in user_token_headers as the headers argument in any client request that requires authentication.

For a test user, use test_user:

def test_user_exists(test_user):
    assert test_user.email == "[email protected]"

For a superuser, use test_superuser.

Superuser routes requires superuser headers:

def test_superuser_method(client, superuser_token_headers):
    # This route requires superuser privelages
    assert client.get("/api/v1/users", headers=superuser_token_headers)

Contributing

Contributing is more than welcome. Please read the Contributing doc to find out more.