azure-static-web-apps

Visão Geral

O Azure Static Web Apps (SWA) hospeda front-ends estáticos com back-ends opcionais de API serverless. A CLI do SWA (swa) fornece emulação de desenvolvimento local e capacidades de implantação.

Recursos principais:

• Emulador local com proxy de API e simulação de autenticação
• Detecção e configuração automática de framework
• Implantação direta no Azure
• Suporte a conexões de banco de dados

Arquivos de configuração:

• swa-cli.config.json - Configurações da CLI, criado pela swa init (nunca crie manualmente)
• staticwebapp.config.json - Configuração de tempo de execução (rotas, autenticação, cabeçalhos, tempo de execução da API) - pode ser criado manualmente

Instruções Gerais

Instalação

npm install -D @azure/static-web-apps-cli

Verificar: npx swa --version

Fluxo de Trabalho Rápido

IMPORTANTE: Sempre use swa init para criar arquivos de configuração. Nunca crie manualmente swa-cli.config.json.

1. swa init - Primeiro passo obrigatório - detecta automaticamente o framework e cria swa-cli.config.json
2. swa start - Executa o emulador local em http://localhost:4280
3. swa login - Autentica com o Azure
4. swa deploy - Implanta no Azure

Arquivos de Configuração

swa-cli.config.json - Criado pela swa init, não crie manualmente:

• Execute swa init para configuração interativa com detecção de framework
• Execute swa init --yes para aceitar os padrões detectados automaticamente
• Edite o arquivo gerado apenas para personalizar configurações após a inicialização

Exemplo de configuração gerada (apenas para referência):

{
  "$schema": "https://aka.ms/azure/static-web-apps-cli/schema",
  "configurations": {
    "app": {
      "appLocation": ".",
      "apiLocation": "api",
      "outputLocation": "dist",
      "appBuildCommand": "npm run build",
      "run": "npm run dev",
      "appDevserverUrl": "http://localhost:3000"
    }
  }
}

staticwebapp.config.json (na origem do aplicativo ou pasta de saída) - Este arquivo PODE ser criado manualmente para configuração de tempo de execução:

{
  "navigationFallback": {
    "rewrite": "/index.html",
    "exclude": ["/images/*", "/css/*"]
  },
  "routes": [
    { "route": "/api/*", "allowedRoles": ["authenticated"] }
  ],
  "platform": {
    "apiRuntime": "node:20"
  }
}

Referência de Linha de Comando

swa login

Autentica com o Azure para implantação.

swa login                              # Interactive login
swa login --subscription-id <id>       # Specific subscription
swa login --clear-credentials          # Clear cached credentials

Flags: --subscription-id, -S | --resource-group, -R | --tenant-id, -T | --client-id, -C | --client-secret, -CS | --app-name, -n

swa init

Configura um novo projeto SWA com base em um frontend existente e API (opcional). Detecta frameworks automaticamente.

swa init                    # Interactive setup
swa init --yes              # Accept defaults

swa build

Compila o frontend e/ou a API.

swa build                   # Build using config
swa build --auto            # Auto-detect and build
swa build myApp             # Build specific configuration

Flags: --app-location, -a | --api-location, -i | --output-location, -O | --app-build-command, -A | --api-build-command, -I

swa start

Inicia o emulador de desenvolvimento local.

swa start                                    # Serve from outputLocation
swa start ./dist                             # Serve specific folder
swa start http://localhost:3000              # Proxy to dev server
swa start ./dist --api-location ./api        # With API folder
swa start http://localhost:3000 --run "npm start"  # Auto-start dev server

Portas comuns de framework:

Flags principais:

• --port, -p - Porta do emulador (padrão: 4280)
• --api-location, -i - Caminho da pasta da API
• --api-port, -j - Porta da API (padrão: 7071)
• --run, -r - Comando para iniciar o servidor de desenvolvimento
• --open, -o - Abre o navegador automaticamente
• --ssl, -s - Habilita HTTPS

swa deploy

Implanta no Azure Static Web Apps.

swa deploy                              # Deploy using config
swa deploy ./dist                       # Deploy specific folder
swa deploy --env production             # Deploy to production
swa deploy --deployment-token <TOKEN>   # Use deployment token
swa deploy --dry-run                    # Preview without deploying

Obter token de implantação:

• Portal do Azure: Static Web App → Visão Geral → Gerenciar token de implantação
• CLI: swa deploy --print-token

…