# Azure Static Web Apps CLI: running the SWA emulator on your machine

> The Azure Static Web Apps CLI is a local development tool for the Azure Static Web Apps service. It serves your static assets, proxies to a dev server or Azure Functions, and emulates the platform's auth and routing, with a caveat the README states plainly: some differences are expected, so always test in Azure.

**Azure/static-web-apps-cli** — Azure Static Web Apps CLI ✨

- Repository: https://github.com/Azure/static-web-apps-cli
- Website: https://aka.ms/swa/cli-local-development
- Stars: 667 · Forks: 157
- Language: TypeScript
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/azure-static-web-apps-cli

## Five capabilities, and the emulator is the point

The SWA CLI is described as a local development tool for Azure Static Web Apps, and the README lists what it can do in five bullets.

It can serve static app assets, or proxy to your app dev server. It can serve API requests, or proxy to APIs running in Azure Functions Core Tools. It can emulate authentication and authorization. It can emulate Static Web Apps configuration, including routing and ACL roles. And it can deploy your app to Azure Static Web Apps.

Four of those five are emulation, which is the reason the tool exists. Azure Static Web Apps is a managed platform where a static site, a set of API functions and an auth layer are deployed together and routed by a config file. Reproducing that routing and auth on your own machine is enough work that most teams do not bother, which is exactly what the CLI absorbs.

The proxying behavior is the quiet part of the design. Rather than serving your frontend build directly, the CLI can point at the dev server your framework already runs, so hot module reload keeps working while the SWA routing rules and role-based access sit in front of it. That is what makes it feel like local development rather than a preview environment.

The dependency list backs up the Azure coupling. The package pulls in `@azure/arm-appservice`, `@azure/arm-resources` and `@azure/arm-subscriptions` for the resource management side, `@azure/identity` for credentials, and `@azure/msal-common` for the authentication protocol, so the auth emulation is not a mock of the real thing but an implementation against the same libraries.

## Install it as a dev dependency and run swa with no arguments

The install is a single npm command, and the README offers it as a project-local dev dependency:

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

A global install is also possible, and the README notes it as an alternative with `npm install -g @azure/static-web-apps-cli`.

The package name on npm is `@azure/static-web-apps-cli`, and the executable it provides is `swa`, mapped in the package manifest from the `bin` entry to `dist/cli/bin.js`.

The recommended first move is to open the app folder at the root, outside any /api or /app folders:

```bash
  cd my-awesome-swa-app
```

And then run the `swa` command alone and follow the interactive prompts:

```bash
  swa
```

The README says this is the best way to get started. Running it bare generates a configuration, builds the project, and then asks whether you want to deploy it to Azure. That last step is worth noticing. A bare `swa` can end with a deployment, so a first run in a directory with the wrong credentials attached can push a half-configured app to a real resource.

The extended command set is small and each command has its own help. `swa login` logs into Azure, `swa init` initializes a new static web app project, `swa start` starts the emulator from a directory or binds to a dev server, `swa deploy` deploys the current project, and `swa build` builds the project. The README points at `swa <command> --help` for the options of each.

## The npx route needs init and start as two separate steps

If you would rather not install the package at all, the same thing runs through npx, and the two steps are explicit rather than interactive.

Create a configuration for your project:

```bash
npx @azure/static-web-apps-cli init
```

Then start the emulator:

```bash
npx @azure/static-web-apps-cli start
```

Once it is running, the app is reachable at `http://localhost:4280`.

The difference from the bare `swa` run is control. The interactive path folds configuration, build and the deploy question into one flow, while the npx path leaves you choosing when each stage happens. For a project where you already know the shape of the config, the explicit form is easier to script and easier to review before anything is deployed.

The README shows the emulator serving at http://localhost:4280. The package's own end-to-end scripts show a different port in use, with the e2e tasks starting the server and probing `http://0.0.0.0:1234`, which is the port the test harness uses rather than the one the emulator serves on.

The documentation lives at azure.github.io/static-web-apps-cli, and the README links both the general `swa` page and the per-command pages under a docs/cli path.

## The emulator differs from the service, and the README says so in bold

The Important Notes section of the README contains the sentence that should decide whether this tool is useful to you. The CLI emulates commonly used capabilities of the Azure Static Web Apps cloud service, some differences are expected, and you should always deploy and test your apps in Azure to confirm behavior.

That is an unusually direct warning, and it is not a formality. The emulator is a local reimplementation of a hosted routing and auth system, and there is no way for it to be byte-for-byte identical to the service. The gaps are the sort that only appear under real conditions, where the deployed environment has a different network path, a different identity provider configuration, and different edge behavior.

The repository structure shows how much surface area is being emulated. There is a `schema/` directory, which is where the config schema lives, a `swa-db-connections/` directory, and a `docs/` folder. The `swa-db-connections/` directory is a reminder that SWA apps can have database connections configured, and that configuration is part of what the platform does for you.

For a team shipping on Azure Static Web Apps, the practical reading is that the CLI is a development accelerator, not a verification step. Local iteration happens against the emulator, and correctness is established by deploying and testing in Azure. The `swa deploy` command exists for that final check, and the interactive first run offers it as the last step.

## The test stack covers unit, end to end and framework detection

The package manifest shows a testing setup that is broader than a typical CLI, which tells you something about how the tool is maintained.

The unit tests run under Vitest with `vitest run --silent --config ./vitest.config.unit.ts`, and there is a separate `vitest.workspace.ts` plus `vitest.config.unit.ts` at the top level. The build itself is plain TypeScript compilation with `tsc`, with a `watch` mode, a `clean` step using rimraf on the dist directory, and a `postbuild` that runs a `copy-assets` script for the non-TypeScript files the CLI needs at runtime.

The end-to-end layer uses Cypress. There are separate `cy:run` and `cy:open` scripts, and a `cypress/` directory with fixtures. Two named e2e flows exist, one for a static fixture and one for a blazor-starter fixture, and both build the project first, start the CLI against a fixture config with `node ./dist/cli/bin.js --config ... start static` or `start blazor-starter`, and then run the Cypress suite against `http://0.0.0.0:1234` using start-server-and-test.

The most interesting script is the detection one. `e2e:detection:prepare-samples` fetches a samples directory from an external repository with degit, `e2e:detection:run` runs a detection script over those samples, and `e2e:detection:test` then verifies the results with Vitest. That is a test of the CLI's ability to recognize different project layouts and frameworks, which is a hard thing to get right and easy to regress.

Releases are managed with semantic-release, with a `release:check` dry run and a `release:changelog` script, so the changelog is generated from commit messages.

## Compared with running a plain static server and with deploying every change

The realistic alternatives for local development of a Static Web Apps project are a generic static file server and the deploy-and-check loop.

A generic static server is simpler and much lighter. It serves your built output from a directory, and for a site with a single index.html and no routing rules, that is often enough. The difference is that the SWA CLI also interprets the platform's configuration, applies the routing rules and the ACL roles, handles the auth flow, and splits traffic between the static assets, the /api routes and the app routes. If your app has none of those, a plain server gives you the same result with less machinery. If it has any of them, the plain server will not reproduce the platform's behavior and you will find out about it in production.

The deploy-every-change loop is the other option, and the SWA CLI does not compete with it so much as shorten it. That loop is exact, since it is the real service, but it is slow and it costs a deployment each time. The CLI lets you keep a dev server with hot reload and still see platform behavior, then deploy once at the end.

There is also the option of the platform's own hosted preview environments for pull requests, which move the check off the developer entirely. The difference is where the check runs. A hosted preview is a real SWA deployment, so it is authoritative but slow and remote. The CLI is fast and local but approximate, which is why the README pairs the two: use the CLI while you work, and deploy when you need to know.

The package is MIT licensed, with the terms in the LICENSE file, and the author field in the manifest is Microsoft Corporation. The repository is not archived and the last push was on 2026-10-20, with the listed releases at v2.0.10 from 2026-07-20 while the manifest version reads 2.1.0.

## Conclusion

Adopt the SWA CLI if you build Azure Static Web Apps and want the platform's routing, auth and API proxying reproduced locally without deploying on every change. Do not adopt it as a general static site server or as a substitute for testing in Azure, since the README is explicit that the emulator differs from the service in places. Verify first that your project layout matches what the CLI expects, in particular a root folder outside any /api or /app directories, and that the config it generates matches the staticwebapp.config.json you intend to ship.

## FAQ

### How do I install the Azure Static Web Apps CLI?

Add it to your project as a dev dependency with `npm install -D @azure/static-web-apps-cli`, or install it globally with `npm install -g @azure/static-web-apps-cli`. The package is published as @azure/static-web-apps-cli and provides the `swa` command.

### How do I start the SWA emulator for a local project?

Open the app folder at the root, outside any /api or /app folders, then run `swa` and follow the interactive prompts, which generate a configuration, build the project and offer a deploy. The npx route is `npx @azure/static-web-apps-cli init` followed by `npx @azure/static-web-apps-cli start`, and the app is then served at http://localhost:4280.

### What does the SWA CLI emulate?

It serves static app assets or proxies to your app dev server, serves API requests or proxies to APIs running in Azure Functions Core Tools, emulates authentication and authorization, emulates Static Web Apps configuration including routing and ACL roles, and can deploy the app to Azure Static Web Apps.

### Is the SWA CLI emulator identical to the Azure service?

No. The README states that the CLI emulates commonly used capabilities of the cloud service, that some differences are expected, and that you should always deploy and test your apps in Azure to confirm behavior.

### Which swa commands are available?

The README lists login to log into Azure, init to initialize a new static web app project, start to start the emulator from a directory or bind to a dev server, deploy to deploy the current project to Azure, and build to build the project. Each command has its own help via `swa <command> --help`.

## Sources

- [Azure/static-web-apps-cli on GitHub](https://github.com/Azure/static-web-apps-cli)
- [License: MIT](https://github.com/Azure/static-web-apps-cli/blob/main/LICENSE)
- [Project website](https://aka.ms/swa/cli-local-development)
- [README](https://github.com/Azure/static-web-apps-cli/blob/main/README.md)
- [Releases](https://github.com/Azure/static-web-apps-cli/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/azure-static-web-apps-cli