Introducing the Azure Static Web Apps CLI

Published 04-06-2021 02:52 PM 9,031 Views
Microsoft

static-web-apps-banner.png

 

 

Azure Static Web Apps seamlessly integrates globally distributed hosting for your static content, serverless APIs powered by Azure Functions, as well as features like authentication, custom routing, and route-based authorization.

 

With the new Static Web Apps CLI, you can now run your entire full-stack web app locally in your development environment and access many of the platform’s capabilities without deploying your app. The CLI hosts your frontend and API on a single localhost endpoint and emulates authentication, custom routing, and authorization rules.

 

Static Web Apps CLI can serve static content from a folder. It also works great with local development servers from any frontend framework, including React, Angular, Next.js, and Blazor WebAssembly.

 

Getting started

 

Install the Static Web Apps CLI from npm:

 

npm install -g @azure/static-web-apps-cli

 

To serve static content from a folder, run:

 

swa start ./my-app

 

Your app is accessible at http://localhost:4280. If you have any custom route logic or settings configured in a staticwebapp.config.json file, it’ll apply them automatically.

 

Run and test your full-stack app

 

Use a framework dev server

 

Most frontend frameworks provide a local dev server that allows you to iterate on your app quickly using features such as hot module reloading. Static Web Apps CLI can proxy traffic to a dev server that’s already running.

 

How you start your app’s dev server depends on your framework. Here are some examples:

 

# Create React App
npm start

 

# Next.js
npm run dev

 

# Blazor WebAssembly
dotnet watch run

 

Then, in a separate terminal, start the CLI and provide your framework dev server’s local address:

 

swa start http://localhost:3000

 

Requests to http://localhost:4280 are proxied to your dev server. Using that endpoint, you can test out how your app interacts with Static Web Apps features like authentication and API functions.

 

Simulate authentication

 

Azure Static Web Apps provides integrated authentication using providers such as GitHub, Twitter, and Azure Active Directory. The Static Web Apps CLI simulates the same authentication flow so you can test your authentication/authorization logic locally.

 

When your app requests a Static Web Apps authentication login URI, such as /.auth/login/github, the CLI displays a page that allows you to log in as any identity by specifying their information. This works with all supported identity providers without any additional configuration.

 

Static Web Apps CLI local authentication pageStatic Web Apps CLI local authentication page

 

You can use this to easily test your app using different identities and roles. The /.auth/me endpoint returns information about the current user, and API function calls include a claims principal header—they work just like they do when your app is deployed to Azure! Learn more about how to access user information from our documentation.

 

Run API functions

 

If your app has an Azure Functions API, you can include its location when you start the Static Web Apps CLI:

 

swa start http://localhost:5000 --api ./api

 

Behind the scenes, as the CLI launches, it also starts the API app using the Azure Functions Core Tools. You can access your API functions at http://localhost:4280/api/*. Because the frontend app and serverless functions are served from the same origin, you don’t have to worry about CORS (cross-origin resource sharing) when you call your APIs.

 

What’s next?

 

Static Web Apps CLI is currently in preview. We're only getting started and have lots more planned!

 

Together with the Azure Static Web Apps VS Code extension, the CLI will play an important role in our local development experience. We plan on offering an integrated debugging experience in VS Code that lets you start your entire stack and attach debuggers to both your frontend and backend apps.

 

While we are initially focusing on running apps locally, we plan on expanding the CLI with more commands such as creating Static Web Apps projects.

 

Try it today

 

Read the Azure Static Web Apps local development documentation to learn more and get started.

 

If you have feedback or would like to contribute, check out the Azure Static Web Apps CLI on GitHub.

 

 

%3CLINGO-SUB%20id%3D%22lingo-sub-2257581%22%20slang%3D%22en-US%22%3EIntroducing%20the%20Azure%20Static%20Web%20Apps%20CLI%3C%2FLINGO-SUB%3E%3CLINGO-BODY%20id%3D%22lingo-body-2257581%22%20slang%3D%22en-US%22%3E%3CP%3E%3CSPAN%20class%3D%22lia-inline-image-display-wrapper%20lia-image-align-center%22%20image-alt%3D%22static-web-apps-banner.png%22%20style%3D%22width%3A%20999px%3B%22%3E%3CIMG%20src%3D%22https%3A%2F%2Ftechcommunity.microsoft.com%2Ft5%2Fimage%2Fserverpage%2Fimage-id%2F270628i4B1969E79B26BCBC%2Fimage-size%2Flarge%3Fv%3Dv2%26amp%3Bpx%3D999%22%20role%3D%22button%22%20title%3D%22static-web-apps-banner.png%22%20alt%3D%22static-web-apps-banner.png%22%20%2F%3E%3C%2FSPAN%3E%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3E%3CA%20href%3D%22https%3A%2F%2Fdocs.microsoft.com%2Fazure%2Fstatic-web-apps%2Foverview%22%20target%3D%22_self%22%20rel%3D%22noopener%20noreferrer%22%3EAzure%20Static%20Web%20Apps%3C%2FA%3E%20seamlessly%20integrates%20globally%20distributed%20hosting%20for%20your%20static%20content%2C%20serverless%20APIs%20powered%20by%20Azure%20Functions%2C%20as%20well%20as%20features%20like%20authentication%2C%20custom%20routing%2C%20and%20route-based%20authorization.%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3EWith%20the%20new%20%3CA%20href%3D%22https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F%40azure%2Fstatic-web-apps-cli%22%20target%3D%22_self%22%20rel%3D%22nofollow%20noopener%20noreferrer%22%3EStatic%20Web%20Apps%20CLI%3C%2FA%3E%2C%20you%20can%20now%20run%20your%20entire%20full-stack%20web%20app%20locally%20in%20your%20development%20environment%20and%20access%20many%20of%20the%20platform%E2%80%99s%20capabilities%20without%20deploying%20your%20app.%20The%20CLI%20hosts%20your%20frontend%20and%20API%20on%20a%20single%20localhost%20endpoint%20and%20emulates%20authentication%2C%20custom%20routing%2C%20and%20authorization%20rules.%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3EStatic%20Web%20Apps%20CLI%20can%20serve%20static%20content%20from%20a%20folder.%20It%20also%20works%20great%20with%20local%20development%20servers%20from%20any%20frontend%20framework%2C%20including%20React%2C%20Angular%2C%20Next.js%2C%20and%20Blazor%20WebAssembly.%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CH2%20id%3D%22toc-hId--495501581%22%20id%3D%22toc-hId--495502356%22%3EGetting%20started%3C%2FH2%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3EInstall%20the%20Static%20Web%20Apps%20CLI%20from%20npm%3A%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CPRE%3Enpm%20install%20-g%20%40azure%2Fstatic-web-apps-cli%3C%2FPRE%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3ETo%20serve%20static%20content%20from%20a%20folder%2C%20run%3A%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CPRE%3Eswa%20start%20.%2Fmy-app%3C%2FPRE%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3EYour%20app%20is%20accessible%20at%20%3CSTRONG%3Ehttp%3A%2F%2Flocalhost%3A4280%3C%2FSTRONG%3E.%20If%20you%20have%20any%20custom%20route%20logic%20or%20settings%20configured%20in%20a%20%3CEM%3Estaticwebapp.config.json%3C%2FEM%3E%20file%2C%20it%E2%80%99ll%20apply%20them%20automatically.%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CH2%20id%3D%22toc-hId-1992011252%22%20id%3D%22toc-hId-1992010477%22%3ERun%20and%20test%20your%20full-stack%20app%3C%2FH2%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CH3%20id%3D%22toc-hId--1612394570%22%20id%3D%22toc-hId--1612395345%22%3EUse%20a%20framework%20dev%20server%3C%2FH3%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3EMost%20frontend%20frameworks%20provide%20a%20local%20dev%20server%20that%20allows%20you%20to%20iterate%20on%20your%20app%20quickly%20using%20features%20such%20as%20hot%20module%20reloading.%20Static%20Web%20Apps%20CLI%20can%20proxy%20traffic%20to%20a%20dev%20server%20that%E2%80%99s%20already%20running.%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3EHow%20you%20start%20your%20app%E2%80%99s%20dev%20server%20depends%20on%20your%20framework.%20Here%20are%20some%20examples%3A%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CPRE%3E%23%20Create%20React%20App%3CBR%20%2F%3Enpm%20start%3C%2FPRE%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CPRE%3E%23%20Next.js%3CBR%20%2F%3Enpm%20run%20dev%3C%2FPRE%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CPRE%3E%23%20Blazor%20WebAssembly%3CBR%20%2F%3Edotnet%20watch%20run%3C%2FPRE%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3EThen%2C%20in%20a%20separate%20terminal%2C%20start%20the%20CLI%20and%20provide%20your%20framework%20dev%20server%E2%80%99s%20local%20address%3A%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CPRE%3Eswa%20start%20http%3A%2F%2Flocalhost%3A3000%3C%2FPRE%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3ERequests%20to%20http%3A%2F%2Flocalhost%3A4280%20are%20proxied%20to%20your%20dev%20server.%20Using%20that%20endpoint%2C%20you%20can%20test%20out%20how%20your%20app%20interacts%20with%20Static%20Web%20Apps%20features%20like%20authentication%20and%20API%20functions.%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CH3%20id%3D%22toc-hId-875118263%22%20id%3D%22toc-hId-875117488%22%3ESimulate%20authentication%3C%2FH3%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3EAzure%20Static%20Web%20Apps%20provides%20%3CA%20href%3D%22https%3A%2F%2Fdocs.microsoft.com%2Fazure%2Fstatic-web-apps%2Fauthentication-authorization%22%20target%3D%22_self%22%20rel%3D%22noopener%20noreferrer%22%3Eintegrated%20authentication%3C%2FA%3E%20using%20providers%20such%20as%20GitHub%2C%20Twitter%2C%20and%20Azure%20Active%20Directory.%20The%20Static%20Web%20Apps%20CLI%20simulates%20the%20same%20authentication%20flow%20so%20you%20can%20test%20your%20authentication%2Fauthorization%20logic%20locally.%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3EWhen%20your%20app%20requests%20a%20Static%20Web%20Apps%20authentication%20login%20URI%2C%20such%20as%20%3CEM%3E%2F.auth%2Flogin%2Fgithub%3C%2FEM%3E%2C%20the%20CLI%20displays%20a%20page%20that%20allows%20you%20to%20log%20in%20as%20any%20identity%20by%20specifying%20their%20information.%20This%20works%20with%20all%20supported%20identity%20providers%20without%20any%20additional%20configuration.%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3E%3CSPAN%20class%3D%22lia-inline-image-display-wrapper%20lia-image-align-center%22%20image-alt%3D%22swa-cli-auth.png%22%20style%3D%22width%3A%20999px%3B%22%3E%3CIMG%20src%3D%22https%3A%2F%2Ftechcommunity.microsoft.com%2Ft5%2Fimage%2Fserverpage%2Fimage-id%2F270624i8CDD98D5F09C5118%2Fimage-size%2Flarge%3Fv%3Dv2%26amp%3Bpx%3D999%22%20role%3D%22button%22%20title%3D%22swa-cli-auth.png%22%20alt%3D%22Static%20Web%20Apps%20CLI%20local%20authentication%20page%22%20%2F%3E%3CSPAN%20class%3D%22lia-inline-image-caption%22%20onclick%3D%22event.preventDefault()%3B%22%3EStatic%20Web%20Apps%20CLI%20local%20authentication%20page%3C%2FSPAN%3E%3C%2FSPAN%3E%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3EYou%20can%20use%20this%20to%20easily%20test%20your%20app%20using%20different%20identities%20and%20roles.%20The%20%3CEM%3E%2F.auth%2Fme%3C%2FEM%3E%20endpoint%20returns%20information%20about%20the%20current%20user%2C%20and%20API%20function%20calls%20include%20a%20claims%20principal%20header%E2%80%94they%20work%20just%20like%20they%20do%20when%20your%20app%20is%20deployed%20to%20Azure!%20Learn%20more%20about%20how%20to%20access%20user%20information%20from%20our%20%3CA%20href%3D%22https%3A%2F%2Fdocs.microsoft.com%2Fazure%2Fstatic-web-apps%2Fuser-information%22%20target%3D%22_self%22%20rel%3D%22noopener%20noreferrer%22%3Edocumentation%3C%2FA%3E.%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CH3%20id%3D%22toc-hId--932336200%22%20id%3D%22toc-hId--932336975%22%3ERun%20API%20functions%3C%2FH3%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3EIf%20your%20app%20has%20an%20%3CA%20href%3D%22https%3A%2F%2Fdocs.microsoft.com%2Fazure%2Fstatic-web-apps%2Fapis%22%20target%3D%22_self%22%20rel%3D%22noopener%20noreferrer%22%3EAzure%20Functions%20API%3C%2FA%3E%2C%20you%20can%20include%20its%20location%20when%20you%20start%20the%20Static%20Web%20Apps%20CLI%3A%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CPRE%3Eswa%20start%20http%3A%2F%2Flocalhost%3A5000%20--api%20.%2Fapi%3C%2FPRE%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3EBehind%20the%20scenes%2C%20as%20the%20CLI%20launches%2C%20it%20also%20starts%20the%20API%20app%20using%20the%20Azure%20Functions%20Core%20Tools.%20You%20can%20access%20your%20API%20functions%20at%20%3CEM%3Ehttp%3A%2F%2Flocalhost%3A4280%2Fapi%2F*%3C%2FEM%3E.%20Because%20the%20frontend%20app%20and%20serverless%20functions%20are%20served%20from%20the%20same%20origin%2C%20you%20don%E2%80%99t%20have%20to%20worry%20about%20CORS%20(cross-origin%20resource%20sharing)%20when%20you%20call%20your%20APIs.%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CH2%20id%3D%22toc-hId--942839304%22%20id%3D%22toc-hId--942840079%22%3EWhat%E2%80%99s%20next%3F%3C%2FH2%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3EStatic%20Web%20Apps%20CLI%20is%20currently%20in%20preview.%20We're%20only%20getting%20started%20and%20have%20lots%20more%20planned!%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3ETogether%20with%20the%20Azure%20Static%20Web%20Apps%20%3CA%20href%3D%22https%3A%2F%2Fmarketplace.visualstudio.com%2Fitems%3FitemName%3Dms-azuretools.vscode-azurestaticwebapps%22%20target%3D%22_self%22%20rel%3D%22noopener%20noreferrer%22%3EVS%20Code%20extension%3C%2FA%3E%2C%20the%20CLI%20will%20play%20an%20important%20role%20in%20our%20local%20development%20experience.%20We%20plan%20on%20offering%20an%20integrated%20debugging%20experience%20in%20VS%20Code%20that%20lets%20you%20start%20your%20entire%20stack%20and%20attach%20debuggers%20to%20both%20your%20frontend%20and%20backend%20apps.%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3EWhile%20we%20are%20initially%20focusing%20on%20running%20apps%20locally%2C%20we%20plan%20on%20expanding%20the%20CLI%20with%20more%20commands%20such%20as%20creating%20Static%20Web%20Apps%20projects.%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CH2%20id%3D%22toc-hId-1544673529%22%20id%3D%22toc-hId-1544672754%22%3ETry%20it%20today%3C%2FH2%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3ERead%20the%20Azure%20Static%20Web%20Apps%20%3CA%20href%3D%22https%3A%2F%2Fdocs.microsoft.com%2Fazure%2Fstatic-web-apps%2Flocal-development%22%20target%3D%22_self%22%20rel%3D%22noopener%20noreferrer%22%3Elocal%20development%20documentation%3C%2FA%3E%20to%20learn%20more%20and%20get%20started.%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3EIf%20you%20have%20feedback%20or%20would%20like%20to%20contribute%2C%20check%20out%20the%20%3CA%20href%3D%22https%3A%2F%2Fgithub.com%2FAzure%2Fstatic-web-apps-cli%22%20target%3D%22_self%22%20rel%3D%22noopener%20noreferrer%22%3EAzure%20Static%20Web%20Apps%20CLI%20on%20GitHub%3C%2FA%3E.%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%0A%3CP%3E%26nbsp%3B%3C%2FP%3E%3C%2FLINGO-BODY%3E%3CLINGO-TEASER%20id%3D%22lingo-teaser-2257581%22%20slang%3D%22en-US%22%3E%3CP%3E%3CSPAN%20class%3D%22lia-inline-image-display-wrapper%20lia-image-align-inline%22%20image-alt%3D%22static-web-apps-blog-cover.png%22%20style%3D%22width%3A%20999px%3B%22%3E%3CIMG%20src%3D%22https%3A%2F%2Ftechcommunity.microsoft.com%2Ft5%2Fimage%2Fserverpage%2Fimage-id%2F270609iC6B1EBCE8A496ED1%2Fimage-size%2Flarge%3Fv%3Dv2%26amp%3Bpx%3D999%22%20role%3D%22button%22%20title%3D%22static-web-apps-blog-cover.png%22%20alt%3D%22static-web-apps-blog-cover.png%22%20%2F%3E%3C%2FSPAN%3E%3C%2FP%3E%0A%3CP%3ERun%20and%20test%20Static%20Web%20Apps%20locally%20with%20API%20functions%2C%20authentication%2C%20authorization%2C%20and%20routing%20rules%3C%2FP%3E%3C%2FLINGO-TEASER%3E%3CLINGO-LABS%20id%3D%22lingo-labs-2257581%22%20slang%3D%22en-US%22%3E%3CLINGO-LABEL%3E.NET%3C%2FLINGO-LABEL%3E%3CLINGO-LABEL%3ENode.js%3C%2FLINGO-LABEL%3E%3CLINGO-LABEL%3EWeb%20Apps%3C%2FLINGO-LABEL%3E%3C%2FLINGO-LABS%3E
Co-Authors
Version history
Last update:
‎Apr 06 2021 02:51 PM
Updated by: