swa
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 |
Log in to Azure
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
Azure subscription ID used by this project. The default is process.env.AZURE_SUBSCRIPTION_ID
.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Azure tenant ID. The default is process.env.AZURE_TENANT_ID
.
Azure client ID.
Azure client secret.
Azure Static Web Apps app name.
Clear persisted credentials before login. The default is false
.
Use the operating system native keychain for persistent credentials. The default is true
.
Disable use of the operating system native keychain.
Global Parameters
Display the version number.
Enable verbose output. Level values include silly
, info
, log
(default), and silent
.
Path to the swa-cli.config.json file.
Configuration used by the CLI.
Print all resolved options. Default is false
.
Show context-sensitive help.
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]
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
Answers "yes" to all prompts, which disables interactive mode. Default is false
.
Global Parameters
Display the version number.
Enable verbose output. Level values include silly
, info
, log
(default), and silent
.
Path to the swa-cli.config.json file.
Configuration used by the CLI.
Print all resolved options. Default is false
.
Show context-sensitive help.
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
(ornpm 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
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
The folder containing the source code of the front end application. Default is .
.
The folder containing the source code of the API application.
The folder containing the built source of the front end application. The path is relative to --app-location
. Default is .
.
The folder containing the staticwebapp.database.config.json file.
Connect to the app dev server at this URL instead of using output location.
Connect to the API server at this URL instead of using output location.
The API server port passed to func start
. Default is 7071.
The host address used for the CLI dev server. Default is localhost
.
The port value to use for the CLI dev server. Default 4280
.
Serve the front end application and API over HTTPS. Default is false
.
The SSL certificate (.crt) used when enabling HTTPS.
The SSL key (.key) used when enabling HTTPS.
Location of a custom shell command or script file to run at startup.
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.
The directory location of the staticwebapp.config.json
file.
Open the browser to the dev server. Default is false.
Pass additional arguments to the func start
command.
Global Parameters
Display the version number.
Enable verbose output. Level values include silly
, info
, log
(default), and silent
.
Path to the swa-cli.config.json file.
Configuration used by the CLI.
Print all resolved options. Default is false
.
Show context-sensitive help.
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]
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
The folder containing the source code of the front-end application. Default is .
.
The folder containing the source code of the API application.
The folder containing the built source of the front-end application. This path is relative to --app-location
. Default is .
.
Builds the front-end application.
Builds the API application.
Automatically detects how to build your front-end and API applications. Default is false
.
Global Parameters
Display the version number.
Enable verbose output. Level values include silly
, info
, log
(default), and silent
.
Path to the swa-cli.config.json file.
Configuration used by the CLI.
Print all resolved options. Default is false
.
Show context-sensitive help.
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 calledSWA_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 youroutputLocation
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 theappLocation
. If you are using aswa-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]
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
Display the version number.
Enable verbose output. Level values include silly
, info
, log
(default), and silent
.
Path to the swa-cli.config.json file.
Configuration used by the CLI.
Print all resolved options. Default is false
.
Show context-sensitive help.
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>
Generate a sample database connection configuration folder for an Azure SQL database.
swa db init --database-type mssql
(Required) The type of the database you want to connect (mssql, postgresql, cosmosdb_nosql, mysql).
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
.
The connection string of the database you want to connect.
The database of your Cosmos DB account you want to connect (only needed if using cosmosdb_nosql database type).
The container of your cosmosdb account you want to connect.
Display help for command.
Global Parameters
Display the version number.
Enable verbose output. Level values include silly
, info
, log
(default), and silent
.
Path to the swa-cli.config.json file.
Configuration used by the CLI.
Print all resolved options. Default is false
.
Show context-sensitive help.