Merge pull request #261365 from craigshoemaker/swa/cli-migration

[Static Web Apps] SWA CLI Article Migration (3 new articles, 2 updates)

Author: v-regandowner

articles/static-web-apps/TOC.yml

@@ -211,12 +211,20 @@
     href: /rest/api/appservice/static-sites
   - name: SWA CLI
     items:
-      - name: Summary
-        href: static-web-apps-cli.yml
+      - name: Overview
+        href: static-web-apps-cli-overview.md
+      - name: Install
+        href: static-web-apps-cli-install.md
+      - name: Start the emulator
+        href: static-web-apps-cli-emulator.md
+      - name: Start the API server
+        href: static-web-apps-cli-api-server.md
+      - name: Deploy to Azure
+        href: static-web-apps-cli-deploy.md
       - name: Configure SWA CLI
         href: static-web-apps-cli-configuration.md
-      - name: Deploy static web app with SWA CLI
-        href: static-web-apps-cli-deploy.md
+      - name: API Reference
+        href: static-web-apps-cli.yml
 - name: Samples & FAQs
   items:
   - name: Samples

articles/static-web-apps/local-development.md

@@ -5,7 +5,7 @@ services: static-web-apps
 author: craigshoemaker
 ms.service: static-web-apps
 ms.topic: how-to
-ms.date: 08/09/2022
+ms.date: 02/05/2024
 ms.author: cshoe
 ms.custom:
 ---
@@ -21,7 +21,7 @@ When published to the cloud, an Azure Static Web Apps site links together many s
 
 These services must communicate with each other, and Azure Static Web Apps handles this integration for you in the cloud.
 
-Running locally, however, these services aren't automatically tied together.
+However, when you run your application locally these services aren't automatically tied together.
 
 To provide a similar experience as to what you get in Azure, the [Azure Static Web Apps CLI](https://github.com/Azure/static-web-apps-cli) provides the following services:
 
@@ -34,34 +34,9 @@ To provide a similar experience as to what you get in Azure, the [Azure Static W
 > [!NOTE]
 > Often sites built with a front-end framework require a proxy configuration setting to correctly handle requests under the `api` route. When using the Azure Static Web Apps CLI the proxy location value is `/api`, and without the CLI the value is `http://localhost:7071/api`.
 
-## How it works
+[!INCLUDE [Local development overview](../../includes/static-web-apps-local-dev-overview.md)]
 
-The following chart shows how requests are handled locally.
-
-:::image type="content" source="media/local-development/cli-conceptual.png" alt-text="Azure Static Web App CLI request and response flow":::
-
-> [!IMPORTANT]
-> Go to `http://localhost:4280` to access the application served by the CLI.
-
-- **Requests** made to port `4280` are forwarded to the appropriate server depending on the type of request.
-
-- **Static content** requests, such as HTML or CSS,  are either handled by the internal CLI static content server, or by the front-end framework server for debugging.
-
-- **Authentication and authorization** requests are handled by an emulator, which provides a fake identity profile to your app.
-
-- **Functions Core Tools runtime**<sup>1</sup> handles requests to the site's API.
-
-- **Responses** from all services are returned to the browser as if they were all a single application.
-
-The following article details the steps for running a node-based application, but the process is the same for any language or environment. Once you start the UI and the Azure Functions API apps independently, then start the Static Web Apps CLI and point it to the running apps using the following command:
-
-```console
-swa start http://localhost:<DEV-SERVER-PORT-NUMBER> --api-location http://localhost:7071
-```
-
-Optionally, if you use the `swa init` command, the Static Web Apps CLI looks at your application code and build a _swa-cli.config.json_ configuration file for the CLI. When you use the _swa-cli.config.json_ file, you can run `swa start` to launch your application locally.
-
-<sup>1</sup> The Azure Functions Core Tools are automatically installed by the CLI if they aren't already on your system.
+The following article details the steps for running a node-based application, but the process is the same for any language or environment.
 
 ## Prerequisites
 
@@ -108,7 +83,7 @@ Open a terminal to the root folder of your existing Azure Static Web Apps site.
 |--|--|--|
 | Serve a specific folder | `swa start ./<OUTPUT_FOLDER_NAME>` | Replace `<OUTPUT_FOLDER_NAME>` with the name of your output folder. |
 | Use a running framework development server | `swa start http://localhost:3000` | This command works when you have an instance of your application running under port `3000`. Update the port number if your configuration is different. |
-| Start a Functions app in a folder | `swa start ./<OUTPUT_FOLDER_NAME> --api-location ./api` | Replace `<OUTPUT_FOLDER_NAME>` with the name of your output folder. This command expects your application's API to have files in the _api_ folder. Update this value if your configuration is different. |
+| Start a Functions app in a folder | `swa start ./<OUTPUT_FOLDER_NAME> --api-location ./api` | Replace `<OUTPUT_FOLDER_NAME>` with the name of your output folder. This command expects your application's API to have files in the `api` folder. Update this value if your configuration is different. |
 | Use a running Functions app | `swa start ./<OUTPUT_FOLDER_NAME> --api-location http://localhost:7071` | Replace `<OUTPUT_FOLDER_NAME>` with the name of your output folder. This command expects your Azure Functions application to be available through port `7071`. Update the port number if your configuration is different. |
 
 ## Authorization and authentication emulation
@@ -135,7 +110,7 @@ Once logged in:
 
 - You can use the `/.auth/me` endpoint, or a function endpoint to retrieve the user's [client principal](./user-information.md).
 
-- Navigating to `/.auth/logout` clears the client principal and logs out the mock user.
+- Navigating to `/.auth/logout` clears the client principal and signs out the mock user.
 
 ## Debugging
 

articles/static-web-apps/static-web-apps-cli-api-server.md

@@ -0,0 +1,57 @@
+---
+title: API server Azure Static Web Apps CLI
+description: API server Azure Static Web Apps CLI
+services: static-web-apps
+author: craigshoemaker
+ms.service: static-web-apps
+ms.topic:  conceptual
+ms.date: 02/02/2024
+ms.author: cshoe
+---
+
+# Start the API server with the Azure Static Web App CLI
+
+In Azure Static Web Apps, you can use the [integrated managed Functions](/azure/static-web-apps/apis-functions) to add API endpoints to your application. You can run an Azure Functions app locally using [Azure Functions core tools CLI](/azure/azure-functions/functions-run-local). The core tools CLI gives you the opportunity to run and debug your API endpoints locally.
+
+You can start the core tools manually or automatically.
+
+## Manual start
+
+To use the SWA CLI emulator alongside the API server:
+
+1. Start API server using the Azure Functions core tools CLI or the [Visual Studio Code Extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions).
+
+    Copy the URL of the local API server, once the core tools are running.
+  
+    ```bash
+    func host start
+    ```
+
+1. In a separate terminal, start the SWA CLI using the `--api-devserver-url` option to pass it the local API Server URI.
+
+    For example:
+  
+    ```bash
+    swa start ./my-dist --api-devserver-url http://localhost:7071
+    ```
+
+## Automatic start
+
+To set up an automatic start, you first need to have an Azure Functions application project located in an `api` folder in your local development environment.
+
+1. Launch the API server alongside the SWA emulator
+
+    ```bash
+    swa start ./my-dist --api-location ./api
+    ```
+
+1. Combine the launch with usage of a running dev server
+
+    ```bash
+    swa start http://localhost:3000 --api-location ./api
+    ```
+  
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Deploy to Azure](static-web-apps-cli-deploy.md)

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

@@ -5,7 +5,7 @@ services: static-web-apps
 author: craigshoemaker
 ms.service: static-web-apps
 ms.topic:  conceptual
-ms.date: 09/30/2022
+ms.date: 02/02/2024
 ms.author: cshoe
 ---
 
@@ -22,9 +22,12 @@ The Azure Static Web Apps (SWA) CLI gets configuration information for your stat
 The configuration file can contain multiple configurations, each identified by a unique configuration name.
 
 - If only a single configuration is present in the *swa-cli.config.json* file, `swa start` uses it by default.
-- 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.
 
-## Configuration file example
+- If options are loaded from a config file, then command line options are ignored.
+
+## Example configuration file
+
+The following code snippet shows the configuration file's shape.
 
 ```json
 {
@@ -39,29 +42,31 @@ The configuration file can contain multiple configurations, each identified by a
 }
 ```
 
+When you only have one configuration section, as shown by this example, then the `swa start` command automatically uses these values.
+
 ## Initialize a configuration file
 
-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.
+You can initialize your configuration file with the `swa init` command. If you run the command against an existing project, then `swa init` tries to guess the configuration settings for you.
 
 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.
 
 ```azstatic-cli
 swa --config <PATH>
 ```
 
-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.
+If the file contains only one named configuration, then that configuration is used by default. If multiple configurations are defined, then you pass the desired configuration name in as an option.
 
 ```azstatic-cli
-swa --config-name
+swa --<CONFIG_NAME>
 ```
 
 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.
 
 ## View configuration
 
-The Static Webs CLI provides a `--print-config` option so you can determine resolved options for your current setup.
+The Static Webs CLI provides a `--print-config` option so you can review your current configuration.
 
-Here is an example of what that output looks like when run on a new project with default settings.
+Here's an example of what that output looks like when run on a new project with default settings.
 
 ```azstatic-cli
 swa --print-config
@@ -105,4 +110,4 @@ Running `swa --print-config` provide's the current configuration defaults.
 
 ## Validate configuration
 
-The swa-cli.config.json file can be validated against the following schema: https://aka.ms/azure/static-web-apps-cli/schema
+You can validate the *swa-cli.config.json* file against the following schema: https://aka.ms/azure/static-web-apps-cli/schema