Configuración del desarrollo local para Azure Static Web Apps

Artículo
02/05/2024

Cuando se publica en la nube, un sitio de Azure Static Web Apps reúne muchos servicios que funcionan juntos como si fueran la misma aplicación. Estos servicios incluyen:

La aplicación web estática
API de Azure Functions
Servicios de autenticación y autorización
Servicios de enrutamiento y configuración

Estos servicios deben comunicarse entre sí y Azure Static Web Apps controla esta integración en la nube.

Sin embargo, cuando se ejecuta la aplicación localmente, estos servicios no se vinculan automáticamente.

Para proporcionar una experiencia similar a la que se obtiene en Azure, la CLI de Azure Static Web Apps proporciona los siguientes servicios:

Un servidor de sitio estático local
Un proxy para el servidor de desarrollo del marco front-end
Un proxy para los puntos de conexión de API: disponible mediante Azure Functions Core Tools
Un servidor ficticio de autenticación y autorización
Aplicación de opciones de configuración y rutas locales

Nota:

A menudo, los sitios creados con un marco de front-end requieren que una opción de configuración de proxy controle solicitudes correctamente en la ruta api. Al usar la CLI de Azure Static Web Apps el valor de ubicación del proxy es /api y, sin la CLI, el valor es http://localhost:7071/api.

Funcionamiento

En el gráfico siguiente se muestra cómo se administran las solicitudes localmente.

Diagram showing the Azure Static Web App CLI request and response flow.

Importante

Vaya a http://localhost:4280 para acceder a la aplicación suministrada por la CLI.

Las solicitudes realizadas al puerto 4280 se reenvían al servidor adecuado según el tipo de solicitud.
Las solicitudes de contenido estático, como HTML o CSS, se administran mediante el servidor interno de contenido estático de la CLI o el servidor del marco de front-end para la depuración.
Las solicitudes de autenticación y autorización se administran mediante un emulador, que proporciona un perfil de identidad falso a la aplicación.
El entorno de ejecución de Functions Core Tools¹ administra las solicitudes a la API del sitio.
Las respuestas de todos los servicios se devuelven al explorador como si fueran toda ellas una sola aplicación.

Una vez que inicie la interfaz de usuario y las aplicaciones de API de Azure Functions de forma independiente, inicie la CLI de Static Web Apps y apúntela a las aplicaciones en ejecución mediante el siguiente comando:

swa start http://localhost:<DEV-SERVER-PORT-NUMBER> --api-location http://localhost:7071

Opcionalmente, si usa el comando swa init, la CLI de Static Web Apps examina el código de la aplicación y compila un archivo de configuración swa-cli.config.json para la CLI. Al usar el archivo swa-cli.config.json, puede ejecutar swa start para iniciar la aplicación localmente.

¹ La CLI instala automáticamente Azure Functions Core Tools si aún no están en el sistema.

En el siguiente artículo se detallan los pasos para ejecutar una aplicación basada en nodos, pero el proceso es el mismo para cualquier lenguaje o entorno.

Requisitos previos

Sitio existente de Azure Static Web Apps: si no tiene una, empiece por la aplicación de inicio vanilla-api.
Node.js con npm: ejecute la versión LTS de Node.js, que incluye acceso a npm.
Visual Studio Code: se usa para depurar la aplicación de API, pero no es necesario para la CLI.

Introducción

Abra un terminal en la carpeta raíz del sitio existente de Azure Static Web Apps.

Instale la CLI.
```
npm install -D @azure/static-web-apps-cli
```
Sugerencia

Si desea instalar la CLI de SWA globalmente, use -g en lugar de -D. Sin embargo, se recomienda encarecidamente instalar SWA como dependencia de desarrollo.
Compile la aplicación si es necesario.

Ejecute npm run build o el comando equivalente para el proyecto.
Inicialice el repositorio de la CLI.
```
swa init
```
Responda a las preguntas que plantea la CLI para comprobar que las opciones de configuración son correctas.
Inicie la CLI.
```
swa start
```
Vaya a http://localhost:4280 para ver la aplicación en el explorador.

Otras maneras de iniciar la CLI

Descripción	Comando	Comentarios
Servir una carpeta específica	`swa start ./<OUTPUT_FOLDER_NAME>`	Reemplace `<OUTPUT_FOLDER_NAME>` por el nombre de la carpeta de salida.
Usar un servidor de desarrollo de marco en ejecución	`swa start http://localhost:3000`	Este comando funciona cuando tiene una instancia de la aplicación que se ejecuta en el puerto `3000`. Actualice el número de puerto si la configuración es diferente.
Iniciar una aplicación de Functions en una carpeta	`swa start ./<OUTPUT_FOLDER_NAME> --api-location ./api`	Reemplace `<OUTPUT_FOLDER_NAME>` por el nombre de la carpeta de salida. Este comando espera que la API de la aplicación tenga archivos en la `api` carpeta . Actualice este valor si la configuración es diferente.
Usar una aplicación de Functions en ejecución	`swa start ./<OUTPUT_FOLDER_NAME> --api-location http://localhost:7071`	Reemplace `<OUTPUT_FOLDER_NAME>` por el nombre de la carpeta de salida. Este comando espera que la aplicación de Azure Functions esté disponible a través del puerto `7071`. Actualice el número de puerto si la configuración es diferente.

Emulación de autorización y autenticación

La CLI de Static Web Apps emula el flujo de seguridad implementado en Azure. Cuando un usuario inicia sesión, puede definir un perfil de identidad falso que se devuelva a la aplicación.

Por ejemplo, si intenta ir a /.auth/login/github, se devuelve una página que le permite definir un perfil de identidad.

Nota:

El emulador funciona con cualquier proveedor de seguridad, no solo con GitHub.

Local authentication and authorization emulator

El emulador ofrece una página que le permite proporcionar los siguientes valores de entidad de seguridad del cliente:

Value	Descripción
Nombre de usuario	Nombre de cuenta asociado al proveedor de seguridad. Este valor aparece como la propiedad `userDetails` en la entidad de seguridad del cliente y se genera automáticamente si no se proporciona ningún valor.
Id. usuario	Valor generado automáticamente por la CLI.
Roles	Una lista de nombres de rol, donde cada nombre está en una nueva línea.
Notificaciones	Una lista de notificaciones de usuario, donde cada nombre está en una nueva línea.

Una vez que ha iniciado sesión:

Puede usar el punto de conexión /.auth/me o un punto de conexión de función para recuperar la entidad de seguridad del cliente del usuario.
Al navegar para /.auth/logout borrar la entidad de seguridad de cliente y cerrar la sesión del usuario ficticio.

Depuración

En una aplicación web estática, hay dos contextos de depuración. El primero es para el sitio de contenido estático y el segundo es para las funciones de API. La depuración local es posible al permitir que la CLI de Static Web Apps use servidores de desarrollo para uno o ambos contextos.

En los pasos siguientes se muestra un escenario común en el que se emplean servidores de desarrollo para los contextos de depuración.

Inicie el servidor de desarrollo de sitio estático. Este comando es específico del marco de front-end que se usa, pero a menudo se incluye en forma de comandos como npm run build, npm start o npm run dev.
Abra la carpeta de la aplicación de API en Visual Studio Code e inicie una sesión de depuración.
Inicie la CLI de Static Web Apps mediante el comando siguiente.
```
swa start http://localhost:<DEV-SERVER-PORT-NUMBER> --appDevserverUrl http://localhost:7071
```
Reemplace <DEV_SERVER_PORT_NUMBER> por el número de puerto del servidor de desarrollo.

Las siguientes capturas de pantallas muestran los terminales en un escenario de depuración típico:

El sitio de contenido estático se está ejecutando mediante npm run dev.

Static site development server

La aplicación de API de Azure Functions ejecuta una sesión de depuración en Visual Studio Code.

Visual Studio Code API debugging

La CLI de Static Web Apps se inicia con ambos servidores de desarrollo.

Azure Static Web Apps CLI terminal

Ahora, las solicitudes que pasan por el puerto 4280 se enrutan al servidor de desarrollo de contenido estático o a la sesión de depuración de la API.

Para más información sobre los distintos escenarios de depuración, con instrucciones sobre cómo personalizar los puertos y las direcciones del servidor, consulte el repositorio de la CLI de Azure Static Web Apps.

Ejemplo de configuración de depuración

Visual Studio Code usa un archivo para habilitar las sesiones de depuración en el editor. Si Visual Studio Code no genera un archivo launch.json, puede situar la siguiente configuración en .vscode/launch.json.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Attach to Node Functions",
            "type": "node",
            "request": "attach",
            "port": 9229,
            "preLaunchTask": "func: host start"
        }
    ]
}

Pasos siguientes

Configuración de la aplicación

Compartir a través de