Frontend¶
Puedes servir apps frontend estáticas con app.frontend() (o router.frontend()).
Esto es útil para herramientas frontend que generan archivos estáticos, como React con Vite, TanStack Router, Astro, Vue, Svelte, Angular, Solid, y otros.
Con estas herramientas, normalmente tienes un paso que construye el frontend, con un comando como:
npm run build
Eso generaría un directorio como ./dist/ con tus archivos frontend.
Puedes usar app.frontend() para servir ese directorio siguiendo las convenciones necesarias para estos frameworks frontend.
FastAPI revisa los path operations primero. Los archivos frontend se revisan solo si ninguna ruta normal coincide, por lo que tu API no se verá afectada.
Servir un Frontend¶
Después de construir tu frontend, por ejemplo con npm run build, pon los archivos generados en un directorio, por ejemplo, dist.
La estructura de tu proyecto podría verse así:
.
├── pyproject.toml
├── app
│ ├── __init__.py
│ └── main.py
└── dist
├── index.html
└── assets
└── app.js
Luego sírvelo con app.frontend():
from fastapi import FastAPI
app = FastAPI()
app.frontend("/", directory="dist")
Con esto, un request a /assets/app.js puede servir dist/assets/app.js.
Si también tienes un path operation de FastAPI, el path operation tiene prioridad.
Routing del Lado del Cliente¶
Muchas apps frontend, incluyendo single-page apps (SPAs), usan routing del lado del cliente. Un path como /dashboard/settings podría no ser un archivo real pero el framework se encargaría de manejarlo.
Así, si se accede a esa URL directamente (en lugar de navegar a través de la app), el backend debería servir la app frontend desde index.html, para que el framework frontend pueda luego manejar el routing del lado del cliente.
Para eso, usa fallback="index.html":
from fastapi import FastAPI
app = FastAPI()
app.frontend("/", directory="dist", fallback="index.html")
FastAPI usa este fallback solo para requests GET y HEAD que parecen navegación del navegador. Los archivos faltantes como JavaScript, CSS, e imágenes siguen devolviendo 404.
Los requests con otros methods, como POST o PUT, a paths que solo coinciden con el fallback del frontend también devuelven 404. Los path operations regulares de FastAPI siguen teniendo mayor prioridad que las rutas del frontend.
Consejo
Por defecto, fallback tiene un valor de fallback="auto". En la mayoría de los casos no necesitarás especificar fallback. Lee más abajo para los detalles.
Esto es lo que querrías con muchas apps frontend que usan routing del lado del cliente, por ejemplo, React con TanStack Router, Vue, Angular, SvelteKit, o Solid.
Página 404 Personalizada¶
También puedes servir una página estática 404.html para paths faltantes del frontend:
from fastapi import FastAPI
app = FastAPI()
app.frontend("/", directory="dist", fallback="404.html")
Esa response mantiene un código de estado 404.
En este caso, FastAPI no servirá index.html para paths faltantes del frontend. Devolverá el archivo 404.html en su lugar.
Consejo
Por defecto, fallback tiene un valor de fallback="auto". Con esto, si se encuentra un archivo 404.html, se usará como fallback automáticamente.
Así, normalmente puedes omitir el argumento fallback.
Esto es útil con herramientas frontend que generan archivos HTML estáticos para cada página, como Astro.
Fallback Automático¶
Por defecto, app.frontend() usa fallback="auto".
Si hay un archivo 404.html en el directorio del frontend, los paths faltantes del frontend sirven ese archivo con código de estado 404.
De lo contrario, si hay un archivo index.html, los paths faltantes de navegación del navegador sirven index.html, que es lo que muchas apps frontend con routing del lado del cliente esperan.
Así, en la mayoría de los casos puedes usar app.frontend("/", directory="dist") sin especificar el argumento fallback.
from fastapi import FastAPI
app = FastAPI()
app.frontend("/", directory="dist")
Deshabilitar Fallback¶
Si no quieres servir un archivo fallback para paths faltantes del frontend, usa fallback=None:
from fastapi import FastAPI
app = FastAPI()
app.frontend("/", directory="dist", fallback=None)
Entonces los paths faltantes del frontend devuelven el 404 normal.
Verificar Directorio¶
Por defecto, app.frontend() verifica que el directorio exista cuando se crea la app.
Esto ayuda a detectar errores de configuración temprano. Por ejemplo, si el directorio de salida del build del frontend falta, FastAPI lanzará un error al iniciar.
Si tus archivos frontend se crean después, por ejemplo por un paso de build separado después de que se crea el objeto app, establece check_dir=False:
from fastapi import FastAPI
app = FastAPI()
app.frontend("/", directory="dist", check_dir=False)
Con check_dir=False, FastAPI no verificará el directorio cuando se crea la app. Si el directorio configurado sigue faltando cuando se maneja un request, FastAPI lanzará un error en ese momento.
Usarlo con APIRouter¶
También puedes añadir archivos frontend a un APIRouter e incluirlo con un prefijo:
from fastapi import APIRouter, FastAPI
app = FastAPI()
router = APIRouter()
router.frontend("/", directory="dist", fallback="index.html")
app.include_router(router, prefix="/app")
En este ejemplo, los paths del frontend se sirven bajo /app.
Cualquier path operations regulares en la app seguirán teniendo precedencia, incluyendo en otros routers.
Solo Salida del Build Estático¶
app.frontend() sirve archivos ya generados por tu build del frontend.
No ejecuta server-side rendering. Es para frameworks frontend que generan archivos estáticos, no para frameworks que necesitan rendering dinámico en el servidor para cada request.