@manekinekko/swa-emu

Azure Static Web Apps Emulator

Introducing SWA EMU, the Azure Static Web Apps Emulator that serves as a local emulator for Azure Static Web Apps. It can:

• Auto-build your local APP and API
• Emulate Authentication
• Serve API requests
• Serve static APP assets

High-level architecture

The SWA EMU is built on top of the following components:

• The Reverse Proxy: this is the heart of the SWA EMU, it's the piece that forwards all HTTP requests to the appropriate components:
  • /.auth/** requests are forwarded to the Auth Emulator server.
  • /api/** requests are forwarded to the localhost API function (if available).
  • /** all other requests are forwarded to the static assets server (serving the front-end app).
• The Auth Emulator server: emulates the whole authentication flow.
• The Static content server: serves the local app static content.
• The Serverless API server (baked by the Azure Function App).

Before SWA EMU bootstraps, it also can read (using the --build options) the local SWA github workflow file (created by Azure Static Web Apps) and builds both the static app and the api according to the user's config. And pretty much like SWA, if the user isn't using an API, SWA EMU will skip the API build.

Authentication emulation flow

The Authentication flow is illustrated in the following sequence diagram (or open in a new tab):

Disclaimer

SWA EMU is still in developer preview and not yet ready for prime time. You will encounter issues, so please report them or help us fix them. Your contributions will be very appreciated 🙏

Quick start

Using npm or yarn:

• Install the emulator: npm install -g @manekinekko/swa-emu@latest
• Open a SWA app folder at the root (outside any /api or /app folders): cd my-awesome-swa-app
• Start the emulator: swa
• Access your SWA app from http://localhost

Using npx:

• Open a SWA app folder at the root (outside any /api or /app folders): cd my-awesome-swa-app
• Start the emulator: npx @manekinekko/swa-emu@latest
• Access your SWA app from http://localhost

Start the emulator from a specific folder

By default, SWA EMU will start from the current directory ./. But if you have multiple SWA projects, you can start SWA EMU with a specific folder, and the emulator will use that folder as the app_location.

If your SWA project is under ./my-app, then run the SWA EMU and provide that folder:

swa ./my-app

Please also note, that running swa ./my-app is equivalent to swa --app-location=./my-app.

In case the SWA EMU cannot determine the right frontend application artifact (dist) folder to serve, you can override this configuration by providing the --app-artifact-location flag:

swa ./my-app --app-artifact-location ./my-app/dist/

Use with a local API dev server

When developing locally on your back-end application, it might be useful to use your local API dev server, to serve your API content and benefit from the built-in features like debugging. In order to use SWA EMU with your local API dev server, follow these two steps:

1. Start your local API dev server (as usual). For example: func start host.
2. Run swa with the --use-api flag of the URI provided by the API dev server, in the following format:

swa --use-api=http://<api-dev-server-host>:<api-dev-server-port>

Use with a local APP dev server

When developing locally on your front-end application, it might be useful to use your local application dev server, that comes with your application CLI, to serve your app content and benefit from the built-in feature like the livereload or HMR (hot module reload) features.

In order to use SWA EMU with your local dev server, follow these two steps:

1. Start your local dev server (as usual). For example: ng serve
2. Run swa with the --use-app flag of the URI provided by the dev server, in the following format:

swa --use-app=http://<app-dev-server-host>:<app-dev-server-port>

Here is a list of the default ports used by popular dev servers:

Tool	Port	Command
Angular	4200	swa --use-app=http://localhost:4200
Vue	8080	swa --use-app=http://localhost:8080
Vite	3000	swa --use-app=http://localhost:3000
Create React App	3000	swa --use-app=http://localhost:3000
Webpack Dev Server	8080	swa --use-app=http://localhost:8080
Parcel	1234	swa --use-app=http://localhost:1234
Stencil	3333	swa --use-app=http://localhost:3333
Hugo	1313	swa --use-app=http://localhost:1313
Elm (live server)	8000	swa --use-app=http://localhost:8000
Ionic	8100	swa --use-app=http://localhost:8100
Svelte (sirv-cli)	5000	swa --use-app=http://localhost:5000
Sapper	3000	swa --use-app=http://localhost:3000
Scully.io	1668	swa --use-app=http://localhost:1668
Gatsby	8000	swa --use-app=http://localhost:8000
Nuxt.js	3000	swa --use-app=http://localhost:3000
Next.js	3000	swa --use-app=http://localhost:3000

Configuration

SWA EMU binds to these default hosts:

• http://localhost:4242: for emulated authentication.
• http://localhost:7071: for the API (baked by the Azure Function App)
• http://localhost:4200: for app assets (the front-end app)

If you need to override the default values, provide the following options:

Options	Description	Default	Example
--api-prefix	the API URL prefix	api	swa --api=prefix=my-api-route
--auth-uri	the Auth URI	http://localhost:4242	swa --auth-uri=http://localhost:8083
--api-uri	the API URI	http://localhost:7071	swa --api-uri=http://localhost:8082
--app-uri	the app URI	http://localhost:4200	swa --app-uri=http://localhost:8081
--use-app	use the app dev server	null	swa --use-app=http://localhost:8080
--use-api	use the api dev server	null	swa --use-api=http://localhost:3000
--host	the emulator host address	0.0.0.0	swa --host=192.168.68.80
--port	the emulator port value	80	swa --port=8080
--build	build the api and app before starting	false	swa --build
--verbose	enable debug logs	false	swa --verbose
--ui	enable dashboard UI	false	swa --ui

Local Emulation

The emulator supports local authentication flow and mocks the following providers:

Provider	Endpoint	Local Emulation
GitHub	.auth/login/github	✅
Twitter	.auth/login/twitter	✅
Google	.auth/login/google	✅
Facebook	.auth/login/facbook	✅
AAD	.auth/login/aad	✅

When requesting the .auth/me endpoint, a mocked user clientPrincipal will be returned by the emulator. Here is an example:

{
  "clientPrincipal": {
    "identityProvider": "twitter",
    "userId": "59cd31faa8c34919ac22c19af50482b8",
    "userDetails": "manekinekko",
    "userRoles": ["anonymous", "authenticated"]
  }
}

NOTE: user roles and ACL are not fully supported (see #7).

Caveats

• Custom routes are not yet supported (see #6)
• Authorization and roles are not fully supported (see #7).
• The emulator is serving all traffic over HTTP (HTTPS support will be added soon) (see #4).
• When using GitHub, the OAuth client ID and client secret are provided as-is for dev purposes ONLY. You should create your own OAuth GitHub app!

Troubleshooting

Port 4242 is unavailable

This means that there is already an instance of Azure Functions Core Tools (assigned to the Auth Emulator) that is running and bound to the default port 4242.

To fix it, either:

• close the other running instance, and run the emulator again.
• run the emulator using a different port: --auth-uri=http://localhost:4243
• force close the other instance by killing its processes: lsof -t -i tcp:4242 | xargs kill

Error: listen EADDRINUSE: address already in use 0.0.0.0:80

This error indicates that another app is running and bound to the default port of the emulator: 80.

To fix it, either:

• close the other running instance, and run the emulator again.
• run the emulator using a different port: --port=8081
• force close the other instance by killing its processes: lsof -t -i tcp:80 | xargs kill

Want to help?

Want to file a bug, contribute some code, or improve the documentation? Excellent! Read up on our guidelines for contributing and then check out one of our issues in the list: community-help.