---
title: FastAPI + React Template
emoji: 💻
colorFrom: blue
colorTo: green
sdk: docker
app_port: 9481
pinned: false
license: mit
short_description: Template to vibe code a demo running on FastAPI + React
hf_oauth: true
---

# docker-space-fastapi-react

This repo is a template to run a FastAPI server hosting a React+Tailwind app in a Hugging Face Space.

Spaces are very well suited to vibe-code demos using Cursor, Lovable, Claude Code, etc. The hardest past is often to correctly configure the tooltip to make it work in the first place. This repo is intended to solve that.

## Main features

- 🚀 Built for HF Spaces
- ✨ Vibe-coding ready (see [PROMPT.md](./PROMPT.md))
- 🤗 Support OAuth (Sign in with Hugging Face)
- ⚡ FastAPI for the API²
- 🎨 React + Tailwind for the UI
- 💾 local SQLLite database + regular backups as HF dataset

## Quick start

1. Duplicate the Space.
2. Set an `HF_TOKEN` as Space secret and `BACKUP_DATASET_ID` as Space variable. These will be used to make regular backups of the database.
3. At this stage, Space should be running correctly on the Hub with a demo.
4. For local development, follow the dev instructions below.
5. Once server is running locally, you can start to edit it. All instructions are located in `PROMPT.md`. Inject that file in the vibe coding tool of your choice and start building!

## Instructions

The backend (Python + FastAPI) and the frontend (TS + React + Tailwind) are located respectively in the `backend/` and `frontend/` folder.

### Prerequisite

To run this app locally, you MUST have `HF_TOKEN` set as environment variable with a valid token. You can generate a new one from your [user settings](https://huggingface.co/settings/tokens). This token is necessary to fake the OAuth workflow. If you click on "Sign in with Huggingface" in your dev environment, you will be authenticated as yourself and your local `HF_TOKEN` will be used. This is a mock to allow local testing while avoiding more complex configuration.

### Backend

To run the backend, you'll need `uv` and Python3.12 installed.
Install dependencies with:

```bash
uv venv
make install
```

And then run the backend server with:

```bash
make dev
```

For more details about backend development, check out [this README](./backend/README.md).

### Frontend

To run the frontend, you'll need nodeJS + pnpm installed.

Install dependencies with:

```bash
pnpm install
```

And then run the frontend app with:

```bash
pnpm dev
```

Once both parts are running, go to the frontend URL. You should see a green "Backend Online" message in the top-right corner. Note that this message is only visible in development mode. When running in a Space, it won't be shown to your end users.

For more details about frontend development, check out [this README](./frontend/README.md).

## Deploy

This repo is meant to be run in a [Docker Space](https://huggingface.co/docs/hub/spaces-sdks-docker).
Configuration should be automatically done if you clone the on the Hugging Face Hub.

If you want to run it on your own, you can use Docker:

```bash
make docker-build
make docker-run
```

When running in Docker, the app runs in production mode without hot-reloading.