Frontend¶

Sie können statische Frontend-Apps mit app.frontend() (oder router.frontend()) bereitstellen.

Das ist nützlich für Frontend-Tools, die statische Dateien generieren, wie React mit Vite, TanStack Router, Astro, Vue, Svelte, Angular, Solid und andere.

Mit diesen Tools haben Sie normalerweise einen Schritt, der das Frontend baut, mit einem Befehl wie:

npmrunbuild

Das würde ein Verzeichnis wie ./dist/ mit Ihren Frontend-Dateien generieren.

Sie können app.frontend() verwenden, um dieses Verzeichnis gemäß den Konventionen bereitzustellen, die von diesen Frontend-Frameworks benötigt werden.

FastAPI prüft zuerst Pfadoperationen. Die Frontend-Dateien werden nur geprüft, wenn keine normale Route gepasst hat, sodass Ihre API nicht beeinträchtigt wird.

Ein Frontend bereitstellen¶

Nachdem Sie Ihr Frontend gebaut haben, zum Beispiel mit npm run build, legen Sie die generierten Dateien in ein Verzeichnis, zum Beispiel dist.

Ihre Projektstruktur könnte so aussehen:

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

Stellen Sie es dann mit app.frontend() bereit:

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

Damit kann ein Request für /assets/app.js dist/assets/app.js ausliefern.

Wenn Sie außerdem eine FastAPI-Pfadoperation haben, gewinnt die Pfadoperation.

Clientseitiges Routing¶

Viele Frontend-Apps, einschließlich Single-Page-Apps (SPAs), verwenden clientseitiges Routing. Ein Pfad wie /dashboard/settings ist möglicherweise keine echte Datei, aber das Framework würde sich darum kümmern, ihn zu handhaben.

Wenn also direkt auf diese URL zugegriffen wird (statt durch die App zu navigieren), sollte das Backend die Frontend-App von index.html bereitstellen, sodass das Frontend-Framework anschließend das clientseitige Routing handhaben kann.

Verwenden Sie dafür fallback="index.html":

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

FastAPI verwendet diesen Fallback nur für GET- und HEAD-Requests, die wie Browser-Navigation aussehen. Fehlende Dateien wie JavaScript, CSS und Bilder geben weiterhin 404 zurück.

Requests mit anderen Methoden, wie POST oder PUT, an Pfade, die nur zum Frontend-Fallback passen, geben ebenfalls 404 zurück. Reguläre FastAPI-Pfadoperationen haben weiterhin eine höhere Priorität als Frontend-Routen.

Das ist das, was Sie bei vielen Frontend-Apps möchten, die clientseitiges Routing verwenden, zum Beispiel React mit TanStack Router, Vue, Angular, SvelteKit oder Solid.

Benutzerdefinierte 404-Seite¶

Sie können auch eine statische 404.html-Seite für fehlende Frontend-Pfade ausliefern:

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

Diese Response behält einen Statuscode von 404.

In diesem Fall liefert FastAPI für fehlende Frontend-Pfade nicht index.html aus. Stattdessen wird die Datei 404.html zurückgegeben.

Das ist nützlich bei Frontend-Tools, die für jede Seite statische HTML-Dateien generieren, wie Astro.

Automatischer Fallback¶

Standardmäßig verwendet app.frontend() fallback="auto".

Wenn es im Frontend-Verzeichnis eine 404.html-Datei gibt, liefern fehlende Frontend-Pfade diese Datei mit dem Statuscode 404 aus.

Andernfalls, wenn es eine index.html-Datei gibt, liefern fehlende Browser-Navigationspfade index.html aus, was viele Frontend-Apps mit clientseitigem Routing erwarten.

In den meisten Fällen können Sie also app.frontend("/", directory="dist") verwenden, ohne das fallback-Argument anzugeben.

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

Fallback deaktivieren¶

Wenn Sie keine Fallback-Datei für fehlende Frontend-Pfade ausliefern möchten, verwenden Sie fallback=None:

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

Dann geben fehlende Frontend-Pfade das normale 404 zurück.

Verzeichnis prüfen¶

Standardmäßig prüft app.frontend(), dass das Verzeichnis existiert, wenn die App erstellt wird.

Das hilft, Konfigurationsfehler früh zu erkennen. Wenn zum Beispiel das Output-Verzeichnis des Frontend-Builds fehlt, löst FastAPI beim Startup einen Fehler aus.

Wenn Ihre Frontend-Dateien später erstellt werden, zum Beispiel durch einen separaten Build-Schritt, nachdem das App-Objekt erstellt wurde, setzen Sie check_dir=False:

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

Mit check_dir=False prüft FastAPI das Verzeichnis nicht, wenn die App erstellt wird. Wenn das konfigurierte Verzeichnis beim Verarbeiten eines Requests immer noch fehlt, löst FastAPI dann einen Fehler aus.

Mit APIRouter verwenden¶

Sie können Frontend-Dateien auch zu einem APIRouter hinzufügen und ihn mit einem Präfix einbinden:

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

In diesem Beispiel werden Frontend-Pfade unter /app bereitgestellt.

Alle regulären Pfadoperationen in der App haben weiterhin Vorrang, auch in anderen Routern.

Nur statischer Build-Output¶

app.frontend() liefert Dateien aus, die bereits von Ihrem Frontend-Build generiert wurden.

Es führt kein serverseitiges Rendering aus. Es ist für Frontend-Frameworks gedacht, die statische Dateien generieren, nicht für Frameworks, die dynamisches Rendering auf dem Server für jeden Request benötigen.