Deploy a Full-Stack App

You can serve a frontend application (built with React, Vue, Svelte, Astro, and others) directly from your FastAPI app, so a single FastAPI Cloud deployment serves both your API and your frontend. ✨

This works with frontends that produce static files during a build step (for example, a dist/ directory). FastAPI serves those files, while your API path operations keep working as usual.

Serve the Frontend from FastAPI

FastAPI serves your frontend’s built static files (usually a dist/ directory) with app.frontend(). For how it works and all its options, see the Serving a Frontend tutorial in the FastAPI docs.

from fastapi import FastAPI

app = FastAPI()


@app.get("/api/health")
def health():
    return {"status": "ok"}


app.frontend("/", directory="dist")

Note

In these examples we assume the frontend build files are in dist/, but some tools may store them in another directory (e.g. build/ or out/).

Use your actual directory name in place of dist/ in app.frontend(), your .gitignore and .fastapicloudignore files, and the steps below.

Deploy from Your Machine

To deploy an app with a frontend from your own machine, you’ll build the frontend, make sure the build is included in your deployment, and then deploy.

Build the Frontend Before Deploying

When you run fastapi deploy, FastAPI Cloud packages and uploads your files and then runs the Python build in the cloud. It does not run your frontend’s build command (like npm run build).

This means you need to build your frontend locally first, so the generated dist/ directory exists before you deploy. You’ll want to rebuild before every deployment, so the deployed files stay in sync with your latest frontend code.

Include the Frontend Build Files in Your Deployment

You’ll most likely want to keep the build output directory (dist/) out of git, since it’s generated and shouldn’t be committed to source control. Add it to your .gitignore (your build tool may have done this for you already):

.gitignore

dist/

But FastAPI Cloud respects .gitignore when uploading files, so an ignored dist/ would be left out of your deployment. To include it anyway, un-ignore it in a .fastapicloudignore file with a leading !:

.fastapicloudignore

!dist/

See Ignore or Un-ignore Files for more details.

Deploy

Before every deployment, run your frontend’s build command first, then deploy the app:

npm run build
fastapi deploy

Your API and your frontend are now served from the same app. 🚀

Note

This example uses npm. If your frontend uses a different package manager, use its build command instead — for example pnpm build, yarn build, or bun run build.

Deploy from CI

The Deploy Tokens page explains how to deploy from a CI system like GitHub Actions.

To deploy an app with a frontend, take that workflow and add a step that builds the frontend before deploying — since dist/ is git-ignored, it isn’t part of your repository, so CI needs to create it by running your frontend’s build command.

The .gitignore and .fastapicloudignore setup described above applies here too, so the freshly built dist/ gets uploaded.

Here’s that workflow with the Install Node.js and Build the frontend steps added (highlighted below):

name: "Deploy"

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  deploy:
    name: "Deploy"
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v5
        with:
          fetch-depth: 0

      - name: Install Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 24

      - name: Build the frontend
        run: |
          npm ci
          npm run build

      - name: Install the latest version of uv
        uses: astral-sh/setup-uv@v7

      - name: Deploy to FastAPI Cloud
        run: uv run fastapi deploy
        env:
          FASTAPI_CLOUD_TOKEN: ${{ secrets.FASTAPI_CLOUD_TOKEN }}
          FASTAPI_CLOUD_APP_ID: ${{ secrets.FASTAPI_CLOUD_APP_ID }}

The Build the frontend step uses npm. Adjust its install and build commands for your package manager, as noted under Deploy from Your Machine - Deploy.

You can generate a starting workflow and set the required secrets automatically with the Setup CI command, then add the frontend build steps shown above.

GitHub integration and frontend builds

For now, the GitHub integration (which deploys your app on every push to your default branch) doesn’t run your frontend’s build command, so it can’t build a frontend on its own just yet.

In the meantime, you can deploy a frontend using the local or CI flow described above.