Frontend¶

Puedes servir apps frontend estáticas con app.frontend() (o router.frontend()).

Esto es útil para herramientas de frontend que generan archivos estáticos, como React con Vite, TanStack Router, Astro, Vue, Svelte, Angular, Solid y otras.

Con estas herramientas, normalmente tienes un paso que construye el frontend, con un comando como:

npmrunbuild

Eso generaría un directorio como ./dist/ con tus archivos frontend.

Puedes usar app.frontend() para servir ese directorio siguiendo las convenciones que necesitan estos frameworks frontend.

FastAPI revisa primero las path operations. Los archivos frontend se revisan solo si ninguna ruta normal coincide, así que tu API no se verá afectada.

Sirve 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():

fromfastapiimport 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 una path operation de FastAPI, la path operation gana.

Routing del lado del cliente¶

Muchas apps frontend, incluidas las 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.

Entonces, si se accede a esa URL directamente (en lugar de navegar por la app), el backend debería servir la app frontend desde index.html, para que el framework frontend pueda manejar el routing del lado del cliente.

Para eso, usa fallback="index.html":

fromfastapiimport 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 métodos, como POST o PUT, a paths que solo coinciden con el fallback del frontend también devuelven 404. Las path operations normales de FastAPI siguen teniendo mayor prioridad que las rutas frontend.

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 frontend faltantes:

fromfastapiimport 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 frontend faltantes. En su lugar, devolverá el archivo 404.html.

Esto es útil con herramientas de 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 frontend, los paths frontend faltantes 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í que, en la mayoría de los casos, puedes usar app.frontend("/", directory="dist") sin especificar el argumento fallback.

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

Desactiva el fallback¶

Si no quieres servir un archivo fallback para paths frontend faltantes, usa fallback=None:

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

Entonces los paths frontend faltantes devuelven el 404 normal.

Revisa el directorio¶

Por defecto, app.frontend() revisa que el directorio exista cuando se crea la app.

Esto ayuda a detectar errores de configuración temprano. Por ejemplo, si falta el directorio de salida del build del frontend, FastAPI lanzará un error al iniciar.

Si tus archivos frontend se crean más tarde, por ejemplo mediante un paso de build separado después de crear el objeto app, configura check_dir=False:

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

Con check_dir=False, FastAPI no revisará el directorio cuando se cree la app. Si el directorio configurado todavía falta cuando se maneja un request, FastAPI lanzará un error en ese momento.

Úsalo con APIRouter¶

También puedes agregar archivos frontend a un APIRouter e incluirlo con un prefijo:

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

En este ejemplo, los paths frontend se sirven bajo /app.

Cualquier path operation regular en la app seguirá teniendo prioridad, incluso en otros routers.

Solo salida estática del build¶

app.frontend() sirve archivos ya generados por tu build del frontend.

No ejecuta renderizado del lado del servidor. Es para frameworks frontend que generan archivos estáticos, no para frameworks que necesitan renderizado dinámico en el servidor para cada request.