mirror of
https://github.com/fastapi/full-stack-fastapi-template.git
synced 2026-09-23 22:22:23 +00:00
117 lines
3.7 KiB
Markdown
117 lines
3.7 KiB
Markdown
# FastAPI Project - Frontend
|
|
|
|
The frontend is built with [Vite](https://vitejs.dev/), [React](https://reactjs.org/), [TypeScript](https://www.typescriptlang.org/), [TanStack Query](https://tanstack.com/query), [TanStack Router](https://tanstack.com/router) and [Tailwind CSS](https://tailwindcss.com/).
|
|
|
|
## Requirements
|
|
|
|
- [Bun](https://bun.sh/) (recommended) or [Node.js](https://nodejs.org/)
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
bun install
|
|
bun run dev
|
|
```
|
|
|
|
* Then open your browser at http://localhost:5173/.
|
|
|
|
Run the backend locally with `uv run fastapi dev` and PostgreSQL in Docker Compose. See [../development.md](../development.md) for the complete setup.
|
|
|
|
To serve the frontend with FastAPI, run `bun run build` from the `frontend` directory and open `http://localhost:8000`. To run the full stack with Docker Compose, use `docker compose watch`.
|
|
|
|
Check the file `package.json` to see other available options.
|
|
|
|
### Removing the frontend
|
|
|
|
If you are developing an API-only app and want to remove the frontend, you can do it easily:
|
|
|
|
* Remove the `./frontend` directory.
|
|
|
|
* In the `backend/app/main.py` file, remove the `app.frontend()` call.
|
|
|
|
* In the `backend/Dockerfile` file, remove the frontend build stage and the `COPY --from=frontend-build` instruction.
|
|
|
|
* In the `compose.override.yml` file, remove the `playwright` service.
|
|
|
|
Done, you have a frontend-less (api-only) app. 🤓
|
|
|
|
## Generate Client
|
|
|
|
### Automatically
|
|
|
|
* Activate the backend virtual environment.
|
|
* From the top level project directory, run the script:
|
|
|
|
```bash
|
|
bash ./scripts/generate-client.sh
|
|
```
|
|
|
|
* Commit the changes.
|
|
|
|
### Manually
|
|
|
|
* Make sure the backend is running.
|
|
|
|
* Download the OpenAPI JSON file from `http://localhost:8000/api/v1/openapi.json` and copy it to a new file `openapi.json` at the root of the `frontend` directory.
|
|
|
|
* To generate the frontend client, run:
|
|
|
|
```bash
|
|
bun run generate-client
|
|
```
|
|
|
|
* Commit the changes.
|
|
|
|
Notice that everytime the backend changes (changing the OpenAPI schema), you should follow these steps again to update the frontend client.
|
|
|
|
## Using a Remote API
|
|
|
|
By default, the built frontend uses the same origin as the FastAPI app. If you want to use a remote API while running the Vite development server, you can set the environment variable `VITE_API_URL` to the URL of the remote API. For example, you can set it in the `frontend/.env` file:
|
|
|
|
```env
|
|
VITE_API_URL=https://my-domain.example.com
|
|
```
|
|
|
|
Then, when you run the frontend, it will use that URL as the base URL for the API.
|
|
|
|
## Code Structure
|
|
|
|
The frontend code is structured as follows:
|
|
|
|
* `frontend/src` - The main frontend code.
|
|
* `frontend/src/assets` - Static assets.
|
|
* `frontend/src/client` - The generated OpenAPI client.
|
|
* `frontend/src/components` - The different components of the frontend.
|
|
* `frontend/src/hooks` - Custom hooks.
|
|
* `frontend/src/routes` - The different routes of the frontend which include the pages.
|
|
|
|
## End-to-End Testing with Playwright
|
|
|
|
The frontend includes initial end-to-end tests using Playwright. To run the tests, you need to have the Docker Compose stack running. Start the stack with the following command:
|
|
|
|
```bash
|
|
docker compose up -d --wait backend
|
|
```
|
|
|
|
Then, you can run the tests with the following command:
|
|
|
|
```bash
|
|
bunx playwright test
|
|
```
|
|
|
|
You can also run your tests in UI mode to see the browser and interact with it running:
|
|
|
|
```bash
|
|
bunx playwright test --ui
|
|
```
|
|
|
|
To stop and remove the Docker Compose stack and clean the data created in tests, use the following command:
|
|
|
|
```bash
|
|
docker compose down -v
|
|
```
|
|
|
|
To update the tests, navigate to the tests directory and modify the existing test files or add new ones as needed.
|
|
|
|
For more information on writing and running Playwright tests, refer to the official [Playwright documentation](https://playwright.dev/docs/intro).
|