design-canvas-plugin-azure-swa

Azure Static Web Apps plugin for Design Canvas.

Create, configure, and deploy Azure Static Web Apps directly from Design Canvas — with a guided wizard, built-in auth configuration, PIM activation, Copilot-assisted error diagnosis, and MCP-compatible plugin commands.

Features

• Guided creation wizard — step-by-step flow: preflight → config → auth → review → deploy → done
• Preflight checks — validates Azure CLI installation, login status, subscription access, and RBAC roles
• PIM activation — detects eligible roles and activates them in-place (no Portal trip required)
• Subscription & resource group pickers — searchable dropdowns with create-new-RG inline
• GitHub Actions source integration — optionally connects a GitHub repo for CI/CD during creation
• Authentication configuration — supports both Simple (built-in) and Custom (app registration) auth modes
• staticwebapp.config.json generation — produces a ready-to-commit auth config based on your selections
• Copilot integration — AI-powered error diagnosis when deployments fail
• Dark/light theme — adapts to Design Canvas theme automatically
• Plugin commands — MCP-compatible commands for automation (get-status, create-swa, get-deploy-result)
• State persistence — remembers last-used configuration across sessions via ctx.services.storage
• Handoff context — exposes deploy results to other plugins via getHandoffContext()

Prerequisites

| Requirement | Details | |---|---| | Azure CLI | az must be installed and on your PATH (install guide) | | Azure login | Run az login before opening the plugin | | RBAC role | One of: Website Contributor, Contributor, or Owner on the target subscription | | Design Canvas | @design-canvas/toolbox ≥ 0.1.0 as a peer dependency |

Tip: If you only have PIM-eligible roles, the plugin will detect them and let you activate just-in-time without leaving the panel.

Install

npm install design-canvas-plugin-azure-swa

Usage

Add to your .designcanvas.json:

{
  "plugins": {
    "azure-swa": { "enabled": true }
  }
}

Wizard Steps

1. Preflight

Validates your environment:

• Azure CLI installed and accessible
• Active az login session
• Required RBAC role on the current subscription
• Lists PIM-eligible roles if direct role is missing

2. Configuration

| Field | Description | Default | |---|---|---| | Name | SWA resource name (globally unique) | — | | Resource Group | Select existing or create new | — | | Location | Azure region | eastus2 | | SKU | Free or Standard | Free | | Source | none, github, or devops | none | | Repo URL | GitHub repo (if source = github) | — | | Branch | Branch to deploy from | main | | App location | Root of your app code | / | | Output location | Build output folder | — | | API location | API folder (optional) | — |

3. Authentication

Choose between two modes:

Simple (built-in)

• Uses SWA's pre-configured providers (Entra ID, GitHub, Twitter)
• No app registration required — routes work at /.auth/login/<provider>
• Config blocks unwanted providers via 404 route rules
• Optionally requires authentication on all routes

Custom (app registration)

• Full control with 6 providers: Entra ID, GitHub, Google, Twitter, Apple, Custom OIDC
• Generates identityProviders config referencing app-setting names
• You must register OAuth apps and set secrets in SWA settings post-creation

4. Review

Shows a summary of all configuration before deployment. Confirm or go back to edit.

5. Deploying

Real-time log output:

1. Creates/ensures resource group
2. Creates the Static Web App
3. Retrieves deployment token
4. Generates staticwebapp.config.json (if auth enabled)

If a step fails, Copilot automatically diagnoses the error.

6. Done

Displays:

• SWA URL (clickable)
• Deployment token (masked, copy button)
• staticwebapp.config.json content (copy button)
• Resource ID
• Reset button to start over

Authentication Config Output

The plugin generates a staticwebapp.config.json that you commit to your repo root.

Simple mode example (GitHub + Entra ID only, require auth):

{
  "routes": [
    { "route": "/.auth/login/twitter", "statusCode": 404 }
  ],
  "responseOverrides": {
    "401": { "redirect": "/.auth/login/aad", "statusCode": 302 }
  }
}

Custom mode example (Entra ID with app registration):

{
  "auth": {
    "identityProviders": {
      "azureActiveDirectory": {
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/{TENANT_ID}/v2.0",
          "clientIdSettingName": "AAD_CLIENT_ID",
          "clientSecretSettingName": "AAD_CLIENT_SECRET"
        }
      }
    }
  },
  "routes": [
    { "route": "/*", "allowedRoles": ["authenticated"] }
  ],
  "responseOverrides": {
    "401": { "redirect": "/.auth/login/aad", "statusCode": 302 }
  }
}

Plugin Commands

Registered as MCP-compatible commands for automation and inter-plugin communication:

| Command | Arguments | Returns | |---|---|---| | get-status | — | { step, preflightPassed, subscription, userName } | | create-swa | Partial SwaConfig (name, resourceGroup, location, etc.) | { success, url, resourceId, error? } | | get-deploy-result | — | { success, url, deploymentToken, resourceId, error? } |

Example: create via command

const result = await ctx.pluginCommands.invoke('azure-swa', 'create-swa', {
  name: 'my-app',
  resourceGroup: 'my-rg',
  location: 'westus2',
  sku: 'Free',
});

Events

The plugin emits events via ctx.emit():

| Event | Payload | When | |---|---|---| | azure-swa:preflight-done | { passed: boolean } | Preflight checks complete | | azure-swa:deploy-complete | { success, url?, resourceId?, error? } | Deployment finishes (success or failure) |

Development

# Install dependencies
npm install

# Build (ESM bundle + .d.ts)
npm run build

# Run verification checks
npm run verify

Build output

dist/
  index.js      # ESM bundle (external: @design-canvas/*)
  index.d.ts    # TypeScript declarations

Project structure

src/
  index.ts      # Main plugin implementation
  icon.svg      # Plugin panel icon (16×16, Azure blue)
  svg.d.ts      # SVG module type declaration
tsup.config.ts  # Build config with import rewriting
package.json
tsconfig.json

How It Works

The plugin proxies all Azure CLI calls through the Design Canvas server endpoint (/__dc/az-exec), which executes az commands on the host machine. This means:

• No Azure SDK bundled — keeps the plugin lightweight (~77 KB)
• Works with any az auth method (device code, browser, service principal)
• Respects existing subscription context and RBAC

Conditional Access / TBCA Handling

If your tenant enforces Token-Based Conditional Access (AADSTS530084), the plugin avoids MS Graph resolution calls. Instead, it:

1. Gets the current UPN from az account show
2. Lists role assignments by subscription scope, filtering client-side by principalName

This ensures the plugin works in restricted enterprise environments.

License

MIT