Skip to content

Commit 5a9eae0

Browse files
Stacyrch140Stacyrch140
authored
Merge pull request #219992 from mtrilbybassett/main
Add SWA CLI content to Learn
2 parents 5747894 + f35c219 commit 5a9eae0

File tree

4 files changed

+785
-0
lines changed

4 files changed

+785
-0
lines changed

‎articles/static-web-apps/TOC.yml

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,14 @@
171171
href: /cli/azure/staticwebapp
172172
- name: REST API
173173
href: /rest/api/appservice/static-sites
174+
- name: SWA CLI
175+
items:
176+
- name: Summary
177+
href: static-web-apps-cli.yml
178+
- name: Configure SWA CLI
179+
href: static-web-apps-cli-configuration.md
180+
- name: Deploy static web app with SWA CLI
181+
href: static-web-apps-cli-deploy.md
174182
- name: Resources
175183
items:
176184
- name: Build your skills with Microsoft Learn training

‎articles/static-web-apps/static-web-apps-cli-configuration.md

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
title: Configure the Azure Static Web Apps CLI
3+
description: Configure the Azure Static Web Apps CLI
4+
services: static-web-apps
5+
author: craigshoemaker
6+
ms.service: static-web-apps
7+
ms.topic: conceptual
8+
ms.date: 09/30/2022
9+
ms.author: cshoe
10+
---
11+
12+
# Configure the Azure Static Web Apps CLI
13+
14+
The Azure Static Web Apps (SWA) CLI gets configuration information for your static web app in one of two ways:
15+
16+
- CLI options (passed in at runtime)
17+
- A CLI configuration file named *swa-cli.config.json*
18+
19+
> [!NOTE]
20+
> By default, the SWA CLI looks for a configuration file named *swa-cli.config.json* in the current directory.
21+
22+
The configuration file can contain multiple configurations, each identified by a unique configuration name.
23+
24+
- If only a single configuration is present in the *swa-cli.config.json* file, `swa start` uses it by default.
25+
- If options are loaded from a config file, then command line options are ignored. For example, if you run `swa start app --ssl`, the `ssl=true` option is not be picked up by the CLI.
26+
27+
## Configuration file example
28+
29+
```json
30+
{
31+
"configurations": {
32+
"app": {
33+
"appDevserverUrl": "http://localhost:3000",
34+
"apiLocation": "api",
35+
"run": "npm run start",
36+
"swaConfigLocation": "./my-app-source"
37+
}
38+
}
39+
}
40+
```
41+
42+
## Initialize a configuration file
43+
44+
Use `swa init` to kickstart the workflow to create a configuration file for a new or existing project. If the project exists, `swa init` tries to guess the configuration settings for you.
45+
46+
By default, the process creates these settings in a *swa-cli.config.json* in the current working directory of your project. This directory is the default file name and location used by `swa` when searching for project configuration values.
47+
48+
```azstatic-cli
49+
swa --config <PATH>
50+
```
51+
52+
If the file contains only one named configuration, then it is used by default. If multiple configurations are defined, you need to specify the one to use as an option.
53+
54+
```azstatic-cli
55+
swa --config-name
56+
```
57+
58+
When the configuration file option is used, the settings are stored in JSON format. Once created, you can manually edit the file to update settings or use `swa init` to make updates.
59+
60+
## View configuration
61+
62+
The Static Webs CLI provides a `--print-config` option so you can determine resolved options for your current setup.
63+
64+
Here is an example of what that output looks like when run on a new project with default settings.
65+
66+
```azstatic-cli
67+
swa --print-config
68+
69+
Options:
70+
- port: 4280
71+
- host: localhost
72+
- apiPort: 7071
73+
- appLocation: .
74+
- apiLocation: <undefined>
75+
- outputLocation: .
76+
- swaConfigLocation: <undefined>
77+
- ssl: false
78+
- sslCert: <undefined>
79+
- sslKey: <undefined>
80+
- appBuildCommand: <undefined>
81+
- apiBuildCommand: <undefined>
82+
- run: <undefined>
83+
- verbose: log
84+
- serverTimeout: 60
85+
- open: false
86+
- githubActionWorkflowLocation: <undefined>
87+
- env: preview
88+
- appName: <undefined>
89+
- dryRun: false
90+
- subscriptionId: <undefined>
91+
- resourceGroupName: <undefined>
92+
- tenantId: <undefined>
93+
- clientId: <undefined>
94+
- clientSecret: <undefined>
95+
- useKeychain: true
96+
- clearCredentials: false
97+
- config: swa-cli.config.json
98+
- printConfig: true
99+
```
100+
101+
Running `swa --print-config` provide's the current configuration defaults.
102+
103+
> [!NOTE]
104+
> If the project has not yet defined a configuration file, this automatically triggers the `swa init` workflow to help you create one.
105+
106+
## Validate configuration
107+
108+
The swa-cli.config.json file can be validated against the following schema: https://aka.ms/azure/static-web-apps-cli/schema

‎articles/static-web-apps/static-web-apps-cli-deploy.md

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
---
2+
title: Deploy a static web app with Azure Static Web Apps CLI
3+
description: Deploy a static web app with Azure Static Web Apps CLI
4+
services: static-web-apps
5+
author: craigshoemaker
6+
ms.service: static-web-apps
7+
ms.topic: conceptual
8+
ms.date: 09/30/2022
9+
ms.author: cshoe
10+
---
11+
12+
# Deploy a static web app with Azure Static Web Apps CLI
13+
14+
The `deploy` command deploys the current project to Azure Static Web Apps.
15+
16+
Some common use cases include:
17+
18+
- Deploy a front-end app without an API
19+
- Deploy a front-end app with an API
20+
- Deploy a Blazor app
21+
22+
## Deployment token
23+
24+
The SWA CLI supports deploying using a deployment token. This is usually useful when deploying from a CI/CD environment. You can get a deployment token either from:
25+
26+
- The [Azure portal](https://portal.azure.com/): **Home → Static Web App → Your Instance → Overview → Manage deployment token**
27+
28+
- If you are using the [Azure CLI](https://aka.ms/azcli), you can get the deployment token of your project using the following command:
29+
30+
```azstatic-cli
31+
az staticwebapp secrets list --name <APPLICATION_NAME> --query "properties.apiKey"
32+
```
33+
34+
- If you are using the Azure Static Web Apps CLI, you can use the following command:
35+
36+
```azstatic-cli
37+
swa deploy --print-token
38+
```
39+
40+
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.
41+
42+
> [!IMPORTANT]
43+
> Don't store deployment tokens in a public repository.
44+
45+
## Deploy a front-end app without an API
46+
47+
You can deploy a front-end application without an API to Azure Static Web Apps by running the following steps:
48+
49+
If your front-end application requires a build step, run `swa build` or refer to your application build instructions.
50+
51+
* **Option 1:** From build folder you would like to deploy, run the deploy command:
52+
53+
```azstatic-cli
54+
cd build/
55+
swa deploy
56+
```
57+
58+
> [!NOTE]
59+
> The *build* folder must contain the static content of your app to be deployed.
60+
61+
* **Option 2:** You can also deploy a specific folder:
62+
63+
1. If your front-end application requires a build step, run `swa build` or refer to your application build instructions.
64+
65+
2. Deploy your app:
66+
67+
```azstatic-cli
68+
swa deploy ./my-dist
69+
```
70+
71+
## Deploy a front-end app with an API
72+
73+
To deploy both the front-end app and an API to Azure Static Web Apps, use the following steps.
74+
75+
1. If your front-end application requires a build step, run `swa build` or refer to your application build instructions.
76+
77+
2. Make sure the API language runtime version in the *staticwebapp.config.json* file is set correctly, for example:
78+
79+
```json
80+
{
81+
"platform": {
82+
"apiRuntime": "node:16"
83+
}
84+
}
85+
```
86+
87+
> [!NOTE]
88+
> If your project doesn't have the *staticwebapp.config.json* file, add one under your `outputLocation` folder.
89+
90+
3. Deploy your app:
91+
92+
```azstatic-cli
93+
swa deploy ./my-dist --api-location ./api
94+
```
95+
96+
### Deploy a Blazor app
97+
98+
To deploy a Blazor app with an API to Azure Static Web Apps, use the following steps:
99+
100+
1. Build your Blazor app in **Release** mode:
101+
102+
```azstatic-cli
103+
dotnet publish -c Release -o bin/publish
104+
```
105+
106+
2. From the root of your project, run the deploy command:
107+
108+
```azstatic-cli
109+
swa deploy ./bin/publish/wwwroot --api-location ./Api
110+
```
111+
112+
## Deploy using the `swa-cli.config.json`
113+
114+
> [!NOTE]
115+
> The path for `outputLocation` must be relative to the `appLocation`.
116+
117+
If you are using a [`swa-cli.config.json`](./static-web-apps-cli-configuration.md) configuration file in your project and have a single configuration entry, for example:
118+
119+
```json
120+
{
121+
"configurations": {
122+
"my-app": {
123+
"appLocation": "./",
124+
"apiLocation": "api",
125+
"outputLocation": "frontend",
126+
"start": {
127+
"outputLocation": "frontend"
128+
},
129+
"deploy": {
130+
"outputLocation": "frontend"
131+
}
132+
}
133+
}
134+
}
135+
```
136+
137+
Then you can deploy your application by running the following steps:
138+
139+
1. If your front-end application requires a build step, run `swa build` or refer to your application build instructions.
140+
141+
2. Deploy your app:
142+
143+
```azstatic-cli
144+
swa deploy
145+
```
146+
147+
If you have multiple configuration entries, you can provide the entry ID to specify which one to use:
148+
149+
```azstatic-cli
150+
swa deploy my-otherapp
151+
```
152+
153+
## Options
154+
155+
Here are the options you can use with `swa deploy`:
156+
157+
- `-a, --app-location <path>`: the folder containing the source code of the front-end application (default: "`.`")
158+
- `-i, --api-location <path>`: the folder containing the source code of the API application
159+
- `-O, --output-location <path>`: the folder containing the built source of the front-end application. The path is relative to `--app-location` (default: "`.`")
160+
- `-w, --swa-config-location <swaConfigLocation>`: the directory where the staticwebapp.config.json file is located
161+
- `-d, --deployment-token <secret>`: the secret token used to authenticate with the Static Web Apps
162+
- `-dr, --dry-run`: simulate a deploy process without actually running it (default: `false`)
163+
- `-pt, --print-token`: print the deployment token (default: `false`)
164+
- `--env [environment]`: the type of deployment environment where to deploy the project (default: "`preview`")
165+
- `-S, --subscription-id <subscriptionId>`: Azure subscription ID used by this project (default: `process.env.AZURE_SUBSCRIPTION_ID`)
166+
- `-R, --resource-group <resourceGroupName>`: Azure resource group used by this project
167+
- `-T, --tenant-id <tenantId>`: Azure tenant ID (default: `process.env.AZURE_TENANT_ID`)
168+
- `-C, --client-id <clientId>`: Azure client ID
169+
- `-CS, --client-secret <clientSecret>`: Azure client secret
170+
- `-n, --app-name <appName>`: Azure Static Web App application name
171+
- `-cc, --clear-credentials`: clear persisted credentials before login (default: `false`)
172+
- `-u, --use-keychain`: enable using the operating system native keychain for persistent credentials (default: `true`)
173+
- `-nu, --no-use-keychain`: disable using the operating system native keychain
174+
- `-h, --help`: display help for command
175+
176+
## Usage
177+
178+
Deploy using a deployment token.
179+
180+
```azstatic-cli
181+
swa deploy ./dist/ --api-location ./api/ --deployment-token <TOKEN>
182+
```
183+
184+
Deploy using a deployment token from the environment variables.
185+
186+
```azstatic-cli
187+
SWA_CLI_DEPLOYMENT_TOKEN=123 swa deploy ./dist/ --api-location ./api/
188+
```
189+
190+
Deploy using `swa-cli.config.json` file
191+
192+
```azstatic-cli
193+
swa deploy
194+
swa deploy myconfig
195+
```
196+
197+
Print the deployment token.
198+
199+
```azstatic-cli
200+
swa deploy --print-token
201+
```
202+
203+
Deploy to a specific environment.
204+
205+
```azstatic-cli
206+
swa deploy --env production
207+
```

0 commit comments

Comments
 (0)