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 ressemblent à une 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() vérifie que le répertoire existe lorsque l'application est créée.

Cela permet de détecter tôt les erreurs de configuration. Par exemple, si le répertoire de sortie du build frontend est manquant, FastAPI lèvera une erreur au démarrage.

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érifiera 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.

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.