Frontend¶

Vous pouvez servir des applications frontend statiques avec app.frontend() (ou router.frontend()).

C'est utile pour les outils frontend qui génèrent des fichiers statiques, comme React avec Vite, TanStack Router, Astro, Vue, Svelte, Angular, Solid, et d'autres.

Avec ces outils, vous avez normalement une étape qui build le frontend, avec une commande comme :

npm run build

Cela générerait un répertoire comme ./dist/ avec vos fichiers frontend.

Vous pouvez utiliser app.frontend() pour servir ce répertoire en suivant les conventions nécessaires à ces frameworks frontend.

FastAPI vérifie d'abord les chemins d'accès. Les fichiers frontend ne sont vérifiés que si aucune route normale ne correspond, donc votre API ne sera pas affectée.

Servir un frontend¶

Après avoir build votre frontend, par exemple avec npm run build, placez les fichiers générés dans un répertoire, par exemple dist.

La structure de votre projet pourrait ressembler à ceci :

.
├── pyproject.toml
├── app
│   ├── __init__.py
│   └── main.py
└── dist
    ├── index.html
    └── assets
        └── app.js

Servez-le ensuite avec app.frontend() :

from fastapi import FastAPI

app = FastAPI()

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

Avec cela, une requête vers /assets/app.js peut servir dist/assets/app.js.

Si vous avez également un chemin d'accès FastAPI, le chemin d'accès est prioritaire.

Routage côté client¶

De nombreuses applications frontend, y compris les applications monopages (SPAs), utilisent le routage côté client. Un chemin comme /dashboard/settings peut ne pas être un vrai fichier, mais le framework se chargerait de le gérer.

Ainsi, si vous accédez directement à cette URL (au lieu de naviguer via l'application), le backend doit servir l'application frontend depuis index.html, afin que le framework frontend puisse ensuite gérer le routage côté client.

Pour cela, utilisez fallback="index.html" :

from fastapi import FastAPI

app = FastAPI()

app.frontend("/", directory="dist", fallback="index.html")

FastAPI utilise ce fallback uniquement pour les requêtes GET et HEAD qui acceptent explicitement HTML avec Accept: text/html ou Accept: application/xhtml+xml, comme le font normalement les requêtes de navigation de navigateur. Les fichiers manquants comme JavaScript, CSS et les images renvoient toujours 404.

Les requêtes avec d'autres méthodes, comme POST ou PUT, vers des chemins qui ne correspondent qu'au fallback frontend renvoient également 404. Les chemins d'accès FastAPI réguliers ont toujours une priorité plus élevée que les routes frontend.

C'est ce que vous souhaitez avec de nombreuses applications frontend qui utilisent le routage côté client, par exemple React avec TanStack Router, Vue, Angular, SvelteKit ou Solid.

Page 404 personnalisée¶

Vous pouvez également servir une page statique 404.html pour les chemins frontend manquants :

from fastapi import FastAPI

app = FastAPI()

app.frontend("/", directory="dist", fallback="404.html")

Cette réponse conserve un code de statut 404.

Dans ce cas, FastAPI ne servira pas index.html pour les chemins frontend manquants. Il renverra le fichier 404.html à la place.

C'est utile avec les outils frontend qui génèrent des fichiers HTML statiques pour chaque page, comme Astro.

Fallback automatique¶

Par défaut, app.frontend() utilise fallback="auto".

S'il y a un fichier 404.html dans le répertoire frontend, les chemins frontend manquants servent ce fichier avec le code de statut 404.

Sinon, s'il y a un fichier index.html, les chemins de navigation de navigateur manquants servent index.html, ce qui est attendu par de nombreuses applications frontend avec routage côté client.

Ainsi, dans la plupart des cas, vous pouvez utiliser app.frontend("/", directory="dist") sans spécifier l'argument fallback.

from fastapi import FastAPI

app = FastAPI()

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

Désactiver le fallback¶

Si vous ne souhaitez pas servir de fichier fallback pour les chemins frontend manquants, utilisez fallback=None :

from fastapi import FastAPI

app = FastAPI()

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

Les chemins frontend manquants renvoient alors le 404 normal.

Vérifier le répertoire¶

Par défaut, app.frontend() utilise check_dir="auto".

Lorsque la variable d'environnement FASTAPI_ENV est définie sur development, FastAPI affiche seulement un avertissement si le répertoire de sortie du build frontend est manquant. La commande fastapi dev définit cette variable d'environnement pour vous si elle n'est pas déjà définie. Cela vous permet de démarrer le backend avant de build ou de démarrer le frontend pendant le développement.

Dans tout autre environnement, FastAPI lève une erreur lorsque l'application est créée. Cela aide à détecter tôt les erreurs de configuration avant de déployer une application sans ses fichiers frontend.

Vous pouvez également définir check_dir=True pour toujours vérifier le répertoire lorsque l'application est créée.

Si vos fichiers frontend sont créés plus tard, par exemple par une étape de build séparée après la création de l'objet app, définissez check_dir=False :

from fastapi import FastAPI

app = FastAPI()

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

Avec check_dir=False, FastAPI ne vérifie pas le répertoire lorsque l'application est créée. Si le répertoire configuré est toujours manquant lorsqu'une requête est traitée, FastAPI lèvera alors une erreur.

L'utiliser avec APIRouter¶

Vous pouvez également ajouter des fichiers frontend à un APIRouter et l'inclure avec un préfixe :

from fastapi import APIRouter, FastAPI

app = FastAPI()
router = APIRouter()

router.frontend("/", directory="dist", fallback="index.html")
app.include_router(router, prefix="/app")

Dans cet exemple, les chemins frontend sont servis sous /app.

Tous les chemins d'accès réguliers dans l'application seront toujours prioritaires, y compris dans d'autres routers.

Dépendances et middleware¶

Les réponses frontend s'exécutent au sein de l'application FastAPI normale, donc le middleware HTTP s'applique à elles.

Les dépendances de l'application, d'un APIRouter et de include_router() s'appliquent également aux réponses frontend. Cela peut être utile pour protéger un frontend avec une authentification par cookie ou similaire.

Les dépendances peuvent également modifier les headers de réponse et ajouter des tâches d'arrière-plan, comme avec les chemins d'accès normaux.

Sortie de build statique uniquement¶

app.frontend() sert des fichiers déjà générés par votre build frontend.

Il n'exécute pas de rendu côté serveur. Il est destiné aux frameworks frontend qui génèrent des fichiers statiques, pas aux frameworks qui nécessitent un rendu dynamique sur le serveur pour chaque requête.