Introducción a Azure Static Web Apps: Despliegue y hosting simplificados

¿Qué es Azure Static Web Apps?

Azure Static Web Apps es un servicio de Azure orientado a publicar aplicaciones web modernas cuyo frontend se genera como contenido estático: HTML, CSS, JavaScript y otros recursos precompilados. El servicio automatiza la publicación de la aplicación cuando cambia el código fuente y puede integrarse con repositorios como GitHub o Azure DevOps.

Aunque el nombre destaque la parte estática, Azure Static Web Apps también permite añadir funcionalidad dinámica mediante endpoints serverless basados en Azure Functions. Esto lo convierte en una opción habitual para aplicaciones SPA, sitios generados estáticamente, frontends Jamstack y proyectos que necesitan un backend ligero sin administrar servidores.

Nota: Una aplicación “estática” no tiene por qué ser simple. Puede consumir APIs, usar autenticación, aplicar reglas de autorización y desplegarse mediante CI/CD. Lo estático hace referencia principalmente a la forma en que se entrega el frontend.

Características principales

Azure Static Web Apps combina varias capacidades que normalmente habría que configurar por separado:

Hosting gestionado para contenido estático
Publica los archivos generados por tu aplicación y los sirve desde una infraestructura gestionada por Azure, sin tener que administrar servidores web.
Despliegue automatizado desde repositorio
El servicio puede generar flujos de CI/CD para publicar la aplicación cuando se realiza un cambio en el código. La documentación oficial contempla escenarios con GitHub Actions y Azure DevOps.
Compatibilidad con frameworks modernos
Puede usarse con aplicaciones Angular, React, Vue, Blazor WebAssembly, Svelte, Gatsby, Hugo, Jekyll, Next.js en escenarios compatibles, Nuxt.js, VuePress o HTML estático, entre otros modelos documentados.
APIs serverless integradas
Permite asociar endpoints de API basados en Azure Functions, normalmente dentro del mismo repositorio, para añadir lógica backend sin desplegar una aplicación web tradicional.
Entornos de staging
Azure Static Web Apps puede crear entornos temporales para revisar cambios antes de fusionarlos en la rama principal, una capacidad útil en flujos con pull requests.
Autenticación y autorización
El servicio incluye mecanismos de autenticación y control de acceso que pueden configurarse para proteger rutas o APIs según roles.
Configuración mediante archivo
Aspectos como rutas, redirecciones, cabeceras, fallback de navegación y reglas de autorización se definen en el archivo staticwebapp.config.json.

Cuándo tiene sentido usar Azure Static Web Apps

Azure Static Web Apps encaja especialmente bien en estos escenarios:

Aplicaciones SPA desarrolladas con frameworks como Angular, React o Vue.
Sitios generados estáticamente con herramientas como Hugo, Jekyll o Gatsby.
Frontends que consumen APIs externas o APIs serverless propias.
Aplicaciones con despliegue frecuente desde Git.
Proyectos que necesitan entornos de preproducción para revisar cambios.
Portales internos o externos con reglas sencillas de autenticación y autorización.

No siempre será la mejor opción si necesitas control avanzado sobre el servidor web, procesos backend de larga duración, ejecución persistente en servidor o una arquitectura basada en contenedores. En esos casos pueden encajar mejor Azure App Service, Azure Container Apps, Azure Kubernetes Service u otros servicios, según el diseño de la solución.

Configuración inicial de Azure Static Web Apps

Requisitos previos

Para crear una Static Web App desde el portal de Azure necesitas:

Una cuenta de Azure activa.
Un repositorio con el código de la aplicación.
Una aplicación que genere una salida estática, por ejemplo una carpeta dist, build, public o equivalente según el framework.
Opcionalmente, una carpeta de API si vas a usar Azure Functions integradas.

Azure CLI puede ser útil para automatizar despliegues o gestionar recursos, pero no es obligatoria para crear una Static Web App desde el portal.

Creación de una Static Web App desde el portal de Azure

El flujo habitual desde el portal es el siguiente:

Accede al portal de Azure.
Busca Static Web Apps.
Selecciona Crear.
Indica la suscripción y el grupo de recursos.
Asigna un nombre a la aplicación.
Selecciona el plan y la región disponibles para el recurso.
Conecta el repositorio desde el que se desplegará la aplicación.
Define la rama, la ubicación del código de la app, la ubicación de la API si existe y la carpeta de salida del build.

Al finalizar, Azure puede generar la configuración de CI/CD necesaria para construir y publicar la aplicación desde el repositorio seleccionado.

Importante: La región seleccionada no debe interpretarse como “la región desde la que se servirá siempre el contenido estático al usuario final”. Azure Static Web Apps gestiona la entrega del contenido como parte del servicio. La región afecta al recurso y a aspectos de la configuración del servicio.

Estructura típica del proyecto

Una estructura sencilla podría ser:

my-static-web-app/
├── api/
│   └── HttpTrigger/
│       ├── __init__.py
│       └── function.json
├── src/
├── staticwebapp.config.json
├── package.json
└── vite.config.js

La estructura exacta depende del framework y del runtime utilizado. Lo importante es indicar correctamente estas rutas en el flujo de despliegue:

app_location: ruta donde se encuentra la aplicación frontend.
api_location: ruta donde se encuentra la API, si existe.
output_location: carpeta generada por el proceso de build.

Por ejemplo:

Framework o herramienta	Carpeta de salida habitual
React con Create React App	`build`
Vite	`dist`
Angular	`dist/<nombre-app>`
Vue CLI	`dist`
Sitio HTML simple	puede no requerir build

Estos valores pueden variar según la configuración del proyecto, por lo que conviene revisarlos antes de crear el workflow.

Configuración con `staticwebapp.config.json`

El archivo staticwebapp.config.json permite definir reglas de comportamiento de la aplicación. No siempre es obligatorio, pero resulta recomendable cuando necesitas controlar navegación, rutas protegidas, redirecciones o cabeceras.

Un ejemplo para una SPA con rutas protegidas podría ser:

{
  "routes": [
    {
      "route": "/api/*",
      "allowedRoles": ["authenticated"]
    }
  ],
  "navigationFallback": {
    "rewrite": "/index.html",
    "exclude": [
      "/images/*",
      "/css/*",
      "/js/*"
    ]
  },
  "responseOverrides": {
    "401": {
      "redirect": "/login",
      "statusCode": 302
    }
  }
}

En este ejemplo:

Las rutas bajo /api/* requieren usuarios autenticados.
Las rutas de navegación de la SPA se redirigen a index.html.
Se excluyen recursos estáticos como imágenes, CSS y JavaScript del fallback de navegación.
Una respuesta 401 puede redirigir al usuario a /login.

Nota: La configuración se versiona con el código. Si cambias rutas, reglas de autorización o fallback de navegación, lo normal es modificar el archivo staticwebapp.config.json y desplegar de nuevo.

Automatización de despliegues con GitHub Actions

Azure Static Web Apps puede integrarse con GitHub Actions para construir y desplegar la aplicación cuando se hace push a una rama determinada o cuando se trabaja con pull requests.

Un workflow mínimo puede tener esta forma:

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
  pull_request:
    types:
      - opened
      - synchronize
      - reopened
      - closed
    branches:
      - main

jobs:
  build_and_deploy:
    if: github.event_name == 'push' || github.event.action != 'closed'
    runs-on: ubuntu-latest
    name: Build and Deploy
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build and deploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: $
          repo_token: $
          action: "upload"
          app_location: "/"
          api_location: "api"
          output_location: "dist"

  close_pull_request:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    name: Close Pull Request Environment
    steps:
      - name: Close pull request environment
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: $
          action: "close"

Ajusta estos valores según tu proyecto:

app_location: ubicación del frontend.
api_location: ubicación de la API. Si no tienes API, puede omitirse o dejarse vacío según el workflow generado.
output_location: carpeta final generada por el build.

Secretos necesarios

El secreto principal es:

AZURE_STATIC_WEB_APPS_API_TOKEN: token de despliegue asociado a la Static Web App.

GITHUB_TOKEN lo proporciona GitHub Actions automáticamente durante la ejecución del workflow, por lo que normalmente no necesitas crearlo manualmente como secreto del repositorio.

Integración de APIs con Azure Functions

Azure Static Web Apps permite incluir una API serverless junto al frontend. En proyectos sencillos, la carpeta de API se mantiene en el mismo repositorio y se despliega junto con la aplicación.

Un ejemplo básico de función HTTP en Python sería:

import logging
import azure.functions as func

def main(req: func.HttpRequest) -> func.HttpResponse:
    logging.info("Solicitud recibida.")

    name = req.params.get("name")

    if not name:
        try:
            req_body = req.get_json()
        except ValueError:
            req_body = {}
        name = req_body.get("name")

    if name:
        return func.HttpResponse(f"Hola, {name}!")

    return func.HttpResponse(
        "Por favor, proporciona un nombre en la solicitud.",
        status_code=400
    )

En un proyecto de Azure Functions con el modelo clásico de Python, esta función iría acompañada de su archivo function.json, por ejemplo:

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": ["get", "post"]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    }
  ]
}

Una estructura posible sería:

api/
└── HttpTrigger/
    ├── __init__.py
    └── function.json

Con el workflow anterior, el valor api_location: "api" indica que esa carpeta contiene el proyecto de API.

Importante: Las versiones de runtime, lenguajes soportados y modelos de programación disponibles pueden variar según la configuración del servicio y del plan. Antes de adoptar un lenguaje o versión concreta para producción, conviene contrastarlo con la documentación oficial vigente del servicio.

Autenticación y autorización

Azure Static Web Apps incluye capacidades de autenticación y autorización integradas. Una vez habilitado el flujo de identidad correspondiente, puedes proteger rutas desde staticwebapp.config.json.

Ejemplo de ruta accesible solo para usuarios autenticados:

{
  "routes": [
    {
      "route": "/admin/*",
      "allowedRoles": ["authenticated"]
    }
  ]
}

También puedes trabajar con roles personalizados, siempre que el diseño de autenticación y asignación de roles lo contemple.

Este enfoque resulta útil para:

Portales internos.
Zonas privadas dentro de una SPA.
APIs que solo deben invocarse por usuarios autenticados.
Entornos de revisión protegidos.

Enrutamiento, redirecciones y fallback de navegación

En aplicaciones SPA es habitual que rutas como /productos/123 o /perfil no existan físicamente como archivos en el servidor. En esos casos, el frontend necesita recibir index.html y resolver la ruta en el cliente.

Para ello se usa navigationFallback:

{
  "navigationFallback": {
    "rewrite": "/index.html",
    "exclude": [
      "/assets/*",
      "/images/*",
      "/favicon.ico"
    ]
  }
}

También puedes definir redirecciones:

{
  "routes": [
    {
      "route": "/docs",
      "redirect": "/documentacion",
      "statusCode": 301
    }
  ]
}

Y cabeceras HTTP:

{
  "globalHeaders": {
    "X-Content-Type-Options": "nosniff",
    "X-Frame-Options": "DENY"
  }
}

Estas reglas ayudan a controlar el comportamiento de la aplicación sin introducir un servidor web propio.

Monitorización y operación

Azure Static Web Apps se gestiona desde el portal de Azure y puede integrarse con herramientas de observabilidad de la plataforma. En la operación diaria conviene revisar:

Estado de despliegues
Verifica si el workflow de CI/CD se ejecuta correctamente y si los builds fallan por errores de dependencias, rutas o configuración.
Métricas del recurso
Consulta las métricas disponibles en Azure Monitor para el recurso de Static Web Apps. La disponibilidad exacta de métricas puede depender de la configuración y del plan.
Logs del pipeline
Para problemas de despliegue, los logs de GitHub Actions o Azure DevOps suelen ser la primera fuente de diagnóstico.
APIs serverless
Si la aplicación incluye Azure Functions, revisa su configuración, errores de runtime y telemetría asociada cuando aplique.
Configuración versionada
Mantén staticwebapp.config.json bajo control de código para auditar cambios en rutas, cabeceras y reglas de autorización.

Buenas prácticas

Al trabajar con Azure Static Web Apps, es recomendable:

Mantener separadas las carpetas de código fuente y salida generada.
Confirmar que output_location coincide con la carpeta real creada por el build.
No almacenar secretos en el repositorio.
Usar entornos de staging o pull requests para validar cambios antes de producción.
Definir reglas explícitas para rutas protegidas.
Revisar las cabeceras HTTP de seguridad necesarias para tu aplicación.
Automatizar el despliegue desde el repositorio en lugar de publicar manualmente.
Documentar la estructura del proyecto y las rutas usadas por el pipeline.

Conclusión

Azure Static Web Apps simplifica el despliegue de aplicaciones web modernas al combinar hosting gestionado, CI/CD desde repositorio, configuración declarativa y APIs serverless basadas en Azure Functions.

Es una opción especialmente atractiva para frontends estáticos, aplicaciones SPA y arquitecturas donde el backend puede resolverse mediante APIs ligeras. Aun así, como en cualquier servicio gestionado, conviene revisar límites, planes, runtimes soportados y requisitos de seguridad antes de llevar una aplicación crítica a producción.

Para ampliar detalles y consultar escenarios actualizados, revisa la documentación oficial de Azure Static Web Apps.