Índice de contenido
FastAPI ofrece mecanismos eficientes para gestionar aplicaciones de cliente (Frontend) construidas con frameworks modernos como Vue, React o Svelte. Esta funcionalidad simplifica el despliegue de interfaces de usuario de una sola página (SPA) junto al backend, optimizando la comunicación y eliminando la necesidad de configurar servidores web independientes.
1. Uso del Método Nativo de Frontend
La forma más directa de servir una interfaz construida en el lado del cliente consiste en utilizar el método nativo proporcionado por el framework. Tras compilar el proyecto de frontend (generando los archivos de distribución en una carpeta como dist mediante comandos de empaquetado), basta con enlazar el directorio de salida directamente en la aplicación principal:
$ app.frontend("/ui", directory="frontend/dist")Este método se encarga de resolver automáticamente las rutas, integrar los enrutadores del cliente (como Vue Router) y servir el archivo index.html principal sin requerir configuraciones adicionales de enrutamiento o gestión manual de errores 404.
2. Estructura del Proyecto y Despliegue Híbrido
En una arquitectura híbrida que combina un backend en FastAPI con una interfaz de cliente moderna, la estructura típica del proyecto separa la lógica de los puntos de acceso (endpoints) de los recursos estáticos compilados:
- Módulo de Backend: Contiene los scripts en Python, la configuración de la base de datos y los enrutadores de la API integrados mediante
include_router. - Directorio de Frontend: Aloja el código fuente de la interfaz y genera la carpeta de distribución con los archivos empaquetados en HTML, CSS y JavaScript.
De este modo, coexisten de forma armónica los servicios de backend de alto rendimiento con la experiencia visual del usuario en una misma aplicación integrada.
3. Implementación Avanzada con Clases Personalizadas (StaticFiles)
En escenarios que requieren un control exhaustivo sobre el almacenamiento en caché y el manejo de respuestas para SPA (como redirigir las solicitudes no encontradas al archivo index.html para que el enrutador del cliente gestione la navegación), es posible implementar una clase personalizada heredada de StaticFiles.
class SpaStaticFiles(StaticFiles):
"""StaticFiles que redirige a index.html en los errores 404 de ruta."""
def lookup_path(self, path: str) -> tuple[str, os.stat_result | None]:
self.all_directories = [os.fspath(CARPETA_UI)]
return super().lookup_path(path)
async def get_response(self, path: str, scope: Scope) -> Response:
if not dist_esta_construido():
return HTMLResponse(PAGINA_SIN_BUILD, status_code=status.HTTP_503_SERVICE_UNAVAILABLE)
servido = path
try:
respuesta = await super().get_response(path, scope)
except StarletteHTTPException as exc:
if exc.status_code != 404 or "." in Path(path).name:
raise
respuesta = await super().get_response("index.html", scope)
servido = "index.html"
return self._con_cache_adequate(servido, respuesta)
app.mount(
"/",
SpaStaticFiles(directory=str(CARPETA_UI), html=True, check_dir=False),
name="ui",
)Esta aproximación avanzada permite administrar las cabeceras HTTP de caché de manera diferenciada, aplicando políticas de inmutabilidad a los recursos con hash en su nombre y asegurando que el archivo principal mantenga una validación constante.