swa

Reference

Commands

Name	Description	Type	Status
swa login	Log in to Azure	SWA Core	GA
swa build	Builds the application. If you have a Node.js application, it will install dependencies first.	SWA Core	GA
swa start	Start the Azure Static Web Apps emulator from a directory or bind to a running dev server.	SWA Core	GA
swa deploy	Deploy the current project to Azure Static Web Apps.	SWA Core	GA
swa db	Generate and edit your Static Web Apps database connections configuration.	SWA Core	GA

Authenticate with Azure to get a deployment token for Azure Static Web Apps, using the swa deploy command.

swa login
          [--subscription-id]
          [--resource-group]
          [--tenant-id]
          [--client-id]
          [--client-secret]
          [--app-name]
          [--clear-credentials]
          [--use-keychain]
          [--no-use-keychain]

Interactive log in to Azure

swa login

--subscription-id, -S

Azure subscription ID used by this project. The default is process.env.AZURE_SUBSCRIPTION_ID.

--resource-group, -R

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--tenant-id, -T

Azure tenant ID. The default is process.env.AZURE_TENANT_ID.

--client-id, -C

Azure client ID.

--client-secret, -CS

Azure client secret.

--app-name, -n

Azure Static Web Apps app name.

--clear-credentials -cc

Clear persisted credentials before login. The default is false.

--use-keychain, -u

Use the operating system native keychain for persistent credentials. The default is true.

--no-use-keychain, -nu

Disable use of the operating system native keychain.

Global Parameters

--version, -v

Display the version number.

--verbose, --V [level]

Enable verbose output. Level values include silly, info, log (default), and silent.

--config, -c [path]

Path to the swa-cli.config.json file.

--config-name, -cn

Configuration used by the CLI.

--print-config, -g

Print all resolved options. Default is false.

--help, -h

Show context-sensitive help.

swa init

Configures a new Azure Static Web Apps project.

Configures a new Azure Static Web Apps project with the Static Web Apps CLI. Interactive mode prompts you for a configuration name, will detect your project settings and the frameworks used. Once complete, a new static web app is created and a swa-cli.config.json file is generated in the current directory. You can run swa init multiple times to create different configurations for your project. You may want to do this if you're working on a monorepo and want to configure different projects. The generated configuration file is used in every command you run with the Static Web Apps CLI. If you have multiple named configurations, you can use the positional argument or --config-name option to specify which configuration you want to use. The following is an example configuration generated by the init command:

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

swa init
          [--yes]

Examples

Create a new configuration interactively.

swa init

Create a new configuration using default values for all options.

swa init --yes

Initialize the project using the configuration named "myApp" from the swa-cli.config.json file.

swa init --config-name myApp

Optional Parameters

--yes, -y

Answers "yes" to all prompts, which disables interactive mode. Default is false.

Global Parameters

--version, -v

Display the version number.

--verbose, --V [level]

Enable verbose output. Level values include silly, info, log (default), and silent.

--config, -c [path]

Path to the swa-cli.config.json file.

--config-name, -cn

Configuration used by the CLI.

--print-config, -g

Print all resolved options. Default is false.

--help, -h

Show context-sensitive help.

swa start

Start the Azure Static Web Apps emulator from a directory or bind to a running dev server.

Serve from a folder

By default, the CLI starts and serves any static content from the current working directory ./:

swa start

If the artifact folder of your static app is under a different folder (for example, ./my-dist), then run the CLI and provide that folder:

swa start ./my-dist

Serve from a dev server

When developing your front-end app locally, it's often useful to use the dev server that comes with your front end framework's CLI. Using the framework CLI allows you to use built-in features like "livereload" and HMR (hot module replacement). To use SWA CLI with your local dev server, follow these two steps:

Start your local dev server as usual. For example, if you are using Angular: ng serve (or npm start).
In a separate terminal, run swa start with the URI provided by the dev server, in the following format:

swa start http://<APP_DEV_SERVER_HOST>:<APP_DEV_SERVER_PORT>

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

Tool	Port	Command
Angular	`4200`	`swa start http://localhost:4200`
Blazor WebAssembly	`5000`	`swa start http://localhost:5000`
Gatsby	`8000`	`swa start http://localhost:8000`
Hugo	`1313`	`swa start http://localhost:1313`
Next.js	`3000`	`swa start http://localhost:3000`
React (Create React App)	`3000`	`swa start http://localhost:3000`
Svelte (sirv-cli)	`5000`	`swa start http://localhost:5000`
Vue	`3000`	`swa start http://localhost:3000`

Instead of starting a dev server separately, you can provide the startup command to the CLI.

# npm start script (React)
swa start http://localhost:3000 --run "npm start"

# dotnet watch (Blazor)
swa start http://localhost:5000 --run "dotnet watch run"

# Jekyll
swa start http://localhost:4000 --run "jekyll serve"

# custom script
swa start http://localhost:4200 --run "./startup.sh"

Then access the application with the emulated services from http://localhost:4280

Serve both the front-end app and API

If your project includes API functions, the CLI will check if the Azure Functions Core Tools are installed and available. If not, the CLI will download and install the right version of the Azure Functions Core Tools.

Start the API server automatically

Run the CLI and provide the folder that contains the API backend (a valid Azure Functions App project):

# static content plus an API
swa start ./my-dist --api-location ./api

# front-end dev server plus an API
swa start http://localhost:3000 --api-location ./api

Start API server manually

When developing your backend locally, sometimes it's useful to run Azure Functions Core Tools separately to serve your API. This allows you to use built-in features like debugging and rich editor support. To use the CLI with your local API backend dev server, follow these two steps:

Start your API using Azure Functions Core Tools: func host start or start debugging in VS Code.
In a separate terminal, run the SWA CLI with the --api-location flag and the URI of the local API server, in the following format:

swa start ./my-dist --api-location http://localhost:7071

Database connections

To start your application with a database connection, use the --data-api-location parameter and point to the folder containing the staticwebapp.database.config.json file.

swa start ./src --data-api-location swa-db-connections

Examples

Start the application with defaults.

swa start

Start the application with a front end dev server.

swa start http://<APP_DEV_SERVER_HOST>:<APP_DEV_SERVER_PORT>

Start the application with a front end and back end dev server.

swa start http://<APP_DEV_SERVER_HOST>:<APP_DEV_SERVER_PORT> --api-location http://localhost:7071

Optional Parameters

--app-location, -a <PATH>

The folder containing the source code of the front end application. Default is ..

--api-location, -i <PATH>

The folder containing the source code of the API application.

--output-location, -O <PATH>

The folder containing the built source of the front end application. The path is relative to --app-location. Default is ..

--data-api-location

The folder containing the staticwebapp.database.config.json file.

--app-devserver-url, -D <URL>

Connect to the app dev server at this URL instead of using output location.

--api-devserver-url, -is <URL>

Connect to the API server at this URL instead of using output location.

--api-port, -j <API_PORT>

The API server port passed to func start. Default is 7071.

--host, -q <HOST>

The host address used for the CLI dev server. Default is localhost.

--port, -p <PORT>

The port value to use for the CLI dev server. Default 4280.

--ssl, -s

Serve the front end application and API over HTTPS. Default is false.

--ssl-cert, -e <SSL_CERT_LOCATION>

The SSL certificate (.crt) used when enabling HTTPS.

--ssl-key, -k <SSL_KEY_LOCATION>

The SSL key (.key) used when enabling HTTPS.

--run, -r <STARTUP_SCRIPT>

Location of a custom shell command or script file to run at startup.

--devserver-timeout, -t <TIME>

The amount of time to wait (in seconds) when connecting to a front end application's dev server or an API server. Default is 60.

--swa-config-location, -w <SWA_CONFIG_FILE_LOCATION>

The directory location of the staticwebapp.config.json file.

--open, -o

Open the browser to the dev server. Default is false.

--func-args, -f <FUNCTION_ARGUMENTS>

Pass additional arguments to the func start command.

Global Parameters

--version, -v

Display the version number.

--verbose, --V [level]

Enable verbose output. Level values include silly, info, log (default), and silent.

--config, -c [path]

Path to the swa-cli.config.json file.

--config-name, -cn

Configuration used by the CLI.

--print-config, -g

Print all resolved options. Default is false.

--help, -h

Show context-sensitive help.

swa build

Builds the application. If you have a Node.js application, it will install dependencies first.

Common use cases include: installing dependencies for the front-end app and API and running the build commands for both, only building the front-end or API project if the other doesn't have a build step.

swa build
          [--app-location]
          [--api-location]
          [--output-location]
          [--app-build-command]
          [--api-build-command]
          [--auto]

Examples

Build the app, and optionally install dependencies.

swa build

Detect how to build your app and run build commands after installing dependencies.

swa build --auto

Install dependencies for the front-end application.

swa build --app-location ./client

Use the configuration named `myApp` in *swa-cli.config.json* to build your front-end application.

swa build myApp

Optional Parameters

--app-location, -a

The folder containing the source code of the front-end application. Default is ..

--api-location, -i

The folder containing the source code of the API application.

--output-location, -O

The folder containing the built source of the front-end application. This path is relative to --app-location. Default is ..

--app-build-command, -A

Builds the front-end application.

--api-build-command, -I

Builds the API application.

--auto

Automatically detects how to build your front-end and API applications. Default is false.

Global Parameters

--version, -v

Display the version number.

--verbose, --V [level]

Enable verbose output. Level values include silly, info, log (default), and silent.

--config, -c [path]

Path to the swa-cli.config.json file.

--config-name, -cn

Configuration used by the CLI.

--print-config, -g

Print all resolved options. Default is false.

--help, -h

Show context-sensitive help.

swa deploy

Deploy the current project to Azure Static Web Apps.

Common use cases include:

Deploy a front end app without an API
Deploy a front end app with an API
Deploy a Blazor app

Deployment token

The SWA CLI supports deploying using a deployment token. This is often useful when deploying from a CI/CD environment. You can get a deployment token either from:

The Azure portal: Home → Static Web App → Your Instance → Overview → Manage deployment token
If you are using the Azure CLI, you can get the deployment token of your project using the following command:
```
az staticwebapp secrets list --name <APPLICATION_NAME> --query "properties.apiKey"
```
If you are using the Azure Static Web Apps CLI, you can use the following command:
```
swa deploy --print-token
```
You can then use that value with the --deployment-token <TOKEN> or you can create an environment variable called SWA_CLI_DEPLOYMENT_TOKEN and set it to the deployment token.

Important: Don't store the deployment token in a public repository. This value must remain a secret.

Deploy a front end app without an API

You can deploy a front end application without an API to Azure Static Web Apps by running the following steps:

If your front-end application requires a build step, run swa build or refer to your application build instructions.

Option 1: From build folder you would like to deploy, run the deploy command:

cd build/
swa deploy

Note: The build folder must contain the static content of your app that you want to deploy. Option 2: You can also deploy a specific folder:

If your front end application requires a build step, run swa build or refer to your application build instructions.
Deploy your app:

swa deploy ./my-dist

Deploy a front-end app with an API

To deploy both the front end app and an API to Azure Static Web Apps, use the following steps:

If your front end application requires a build step, run swa build or refer to your application build instructions.
Make sure the API language runtime version in the staticwebapp.config.json file is set correctly, for example:

{
  "platform": {
    "apiRuntime": "node:16"
  }
}

Note: If your project doesn't have any staticwebapp.config.json file, add one under your outputLocation folder.

Deploy your app:

swa deploy ./my-dist --api-location ./api

Deploy a Blazor app

To deploy a Blazor app with an optional API to Azure Static Web Apps, use the following steps:

Build your Blazor app in Release mode:

dotnet publish -c Release -o bin/publish

From the root of your project, run the deploy command:

swa deploy ./bin/publish/wwwroot --api-location ./Api

Deploy using the `swa-cli.config.json`

Note: The path for outputLocation must be relative to the appLocation. If you are using a swa-cli.config.json configuration file in your project and have a single configuration entry, use a configuration like this:

{
  "configurations": {
    "my-app": {
      "appLocation": "./",
      "apiLocation": "api",
      "outputLocation": "frontend",
      "start": {
        "outputLocation": "frontend"
      },
      "deploy": {
        "outputLocation": "frontend"
      }
    }
  }
}

Then you can deploy your application by running the following steps:

If your front-end application requires a build step, run swa build or refer to your application build instructions.
Deploy your app:

swa deploy

If you have multiple configuration entries, you can provide the entry ID to specify which one to use:

swa deploy my-otherapp

swa deploy
          [--yes]

Examples

Deploy using a deployment token.

swa deploy ./dist/ --api-location ./api/ --deployment-token <TOKEN>

Deploy using a deployment token from the environment variables

SWA_CLI_DEPLOYMENT_TOKEN=123 swa deploy ./dist/ --api-location ./api/

Deploy using `swa-cli.config.json` file

swa deploy swa deploy myconfig

Print the deployment token

swa deploy --print-token

Deploy to a specific environment

swa deploy --env production

Global Parameters

--version, -v

Display the version number.

--verbose, --V [level]

Enable verbose output. Level values include silly, info, log (default), and silent.

--config, -c [path]

Path to the swa-cli.config.json file.

--config-name, -cn

Configuration used by the CLI.

--print-config, -g

Print all resolved options. Default is false.

--help, -h

Show context-sensitive help.

swa db

Generate and edit your Static Web Apps database connections configuration.

Use swa db init to generate a sample swa-db-connections folder, along with a staticwebapp.database.config.json configuration file. If you are using a Cosmos DB for NoSQL database, this will also generate a sample staticwebapp.database.schema.gql schema file.

swa db init --database-type <DATABASE_TYPE>

Examples

Generate a sample database connection configuration folder for an Azure SQL database.

swa db init --database-type mssql

Optional Parameters

--database-type, -t <DATABASE_TYPE>

(Required) The type of the database you want to connect (mssql, postgresql, cosmosdb_nosql, mysql).

--folder-name, -f <FOLDER_NAME>

A folder name to override the convention database connection configuration folder name (ensure that you update your CI/CD workflow files accordingly). The default value is swa-db-connections.

---connection-string, -cs <CONNECTION_STRING>

The connection string of the database you want to connect.

--cosmosdb_nosql-database, -nd <COSMOSDB_NOSQL_DATABASE>

The database of your Cosmos DB account you want to connect (only needed if using cosmosdb_nosql database type).

--cosmosdb_nosql-container, -nc <COSMOSDB_NOSQL_CONTAINER>

The container of your cosmosdb account you want to connect.

--help, -h

Display help for command.

Global Parameters

--version, -v

Display the version number.

--verbose, --V [level]

Enable verbose output. Level values include silly, info, log (default), and silent.

--config, -c [path]

Path to the swa-cli.config.json file.

--config-name, -cn

Configuration used by the CLI.

--print-config, -g

Print all resolved options. Default is false.

--help, -h

Show context-sensitive help.

swa

Commands

swa init

Examples

Optional Parameters

swa start

Serve from a folder

Serve from a dev server

Serve both the front-end app and API

Start the API server automatically

Start API server manually

Database connections

Examples

Optional Parameters

swa build

Examples

Optional Parameters

swa deploy

Deployment token

Deploy a front end app without an API

Deploy a front-end app with an API

Deploy a Blazor app

Deploy using the `swa-cli.config.json`

Examples

swa db

Examples

Optional Parameters

Feedback

Additional resources

swa

Commands

swa login

Examples

Optional Parameters

swa init

Examples

Optional Parameters

swa start

Serve from a folder

Serve from a dev server

Serve both the front-end app and API

Start the API server automatically

Start API server manually

Database connections

Examples

Optional Parameters

swa build

Examples

Optional Parameters

swa deploy

Deployment token

Deploy a front end app without an API

Deploy a front-end app with an API

Deploy a Blazor app

Deploy using the swa-cli.config.json

Examples

swa db

Examples

Optional Parameters

Feedback

Additional resources

Deploy using the `swa-cli.config.json`