On May 12, 2021, the Azure Static Web Apps service hit a significant milestone - becoming generally available with support for many of the popular front-end frameworks and static site generators used for modern web app development.

On May 12, 2022, Azure Static Web Apps will make the first-year anniversary of that milestone - making this the perfect time to look back on all the progress made, and look ahead to what's in store next.

Celebrate with #SWAanniversary​

On May 19, 2022, join us live on Learn TV for a 2-hour celebration with some of our favorite speakers and guests from both Microsoft and the larger developer community. Can you tell we're excited for this birthday?

Check out the Event page to learn more about the speakers and topics on the agenda. Add the event to your calendar, and join us live - or bookmark this page and revisit it for links to relevant resources and video replays.

Learn with #30DaysOfSWA​

But there's more! Are you new to Azure Static Web Apps? Do you want to get a beginner-friendly tour of the core concepts, usage examples, developer tools, and best practices involved in building and deploy modern web applications with this service?

You're in luck!

Watch this space for an update on a new content series that will help you jumpstart that learning journey! Throughout the month of May, we'll bring together a diverse group of technologists to share short articles with resources and insights on a curated tour of Static Web Apps - taking you from code to scale.

How Can You Participate?​

Some actions you can take today to get ready for a fun month of learning:

• Bookmark this Series page or Subscribe to the RSS feed
• Follow the #staticwebapps tag on dev.to - and consider making a post there!
• Introduce yourself on our Discussions Forum - tell us what you hope to learn!

Self-Study Resources​

Our goal is to help make this a beginner-friendly learning journey into Azure Static Web Apps. We hope we inspire you to keep going beyond #30Days - and wanted to share resources to motivate you to keep going. Here are three links to bookmark:

• The Resources page - will be updated with links related to each article in the series, all through May! Use this to explore detours and deep dives.
• The Microsoft Learn Path - teaches you how to build your first Static Web Apps powered experience - with React, Angular, Vue and Blazor coding options.
• The #30DaysOfSWA Collection - a Microsoft-specific collection of resources (from documentation to videos and code samples) that I will continue to update.

Thank you for joining us on this fun and functional tour of Azure Static Web Apps. Whether you're new to the technology, or an experienced user, we hope there's something that interests and motivates you to keep going.

Hello #30DaysOfSWA​

Simply put, it's a month-long series of blog posts that provides you a curated and structured tour through the universe of Azure Static Web Apps.

• Each article will be 5 mins or less in reading time
• Each ends with an activity to help reinforce the learning
• Articles will follow a structured roadmap over 4 weeks

We've organized the journey into four stages, each building on the previous one in a way that mimics the developer experience with any new technology:

• Week 1: Focus on Core Concepts, learning terminology and getting setup.
• Week 2: Focus on Usage Examples with quickstarts & front-end technologies.
• Week 3: Focus on Dev Tools to develop, debug, test, and deploy, the SWA!
• Week 4: Focus on Best Practices, from services to end-to-end experiences.

Week 1 Roadmap​

We are kicking off week 1 with a focus on Core Concepts to get you familiar with the high-level architecture, fundamental components and basic terminology for Azure Static Web Apps. Want a sneak peek at the topics? Here's a visual guide to help you!

By the end of week 1 you should know:

• What Azure Static Web Apps is, and its benefits
• How to get started building SWA or using it for your existing apps
• How to go serverless, adding API capability with Azure Functions
• How to configure SWA - from app behavior to build process
• How to secure SWA - from user authentication to role-based authorization
• How to preview SWA - on pull requests or test branches
• How to deploy SWA - using different code sources, or CI/CD options

By the end of the week you should be familiar with SWA terminology and developer workflows - and be ready to explore usage scenarios with various front-end frameworks or static site generators!

Take The Journey​

They say it takes 30 days to make a habit. It's our hope that doing short bursts of reading and activity with Azure Static Web Apps on a daily basis, will lead to better learning and development habits in general.

We want to make it easy for you to participate - here are options to follow along:

• Bookmark this site and visit daily
• Subscribe to the RSS Feed in your favorite Feed Reader
• Visit the dev.to Series Page and like, comment on, or bookmark, the posts.

Want to really get the most from this? Try the exercises each day, and take a moment on a weekly basis, to write a blog post or capture your own notes on what your main takeaways were. As a fan of visual storytelling I know that writing things down helps improve your understanding and recall of the material!

Provide Us Feedback​

We want to make this useful and beginner-friendly! So if you have comments or questions that can help us improve this content, please drop us a note in our Discussions board!

Meet The Authors​

Articles are written by a multi-disciplinary team of contributors from across Microsoft and the community - including members of the Static Web Apps product group and Microsoft Developer Relations.

We'll keep this page updated on a daily basis, to reflect the latest author whose post was published. We'll kick things off with the authors of this post.

• Nitya Narasimhan, Senior Cloud Advocate @Microsoft
• Reshmi Sriram, Static Web Apps PM @Microsoft
• Simona Cotin, Principal PM @Microsoft
• Glaucia Lemos, JS Cloud Advocate @Microsoft
• Anthony Chu, Senior Product PM @Microsoft
• Joseph Lin Software Engineer @Microsoft,
• Mitali Karmarkar, Software Engineer @Microsoft
• Michail Shaposhnikov, Software Engineer @Microsoft
• Chris Noring, Senior Cloud Advocate @Microsoft
• Jen Looper, Principal Cloud Advocate @Microsoft
• to be updated daily ...

Each post will identify the authors by name, and link to a relevant online profile. This series is a labor of love, so if you like a post - show that author some love by providing feedback or saying hello on their identified profile!

Let's Get Started!​

I think that's all you need to know for now! Hope your're as excited as we are. Check back for the next post and ... #LetsDoThis !!

This week, we'll focus on the Core Concepts behind Azure Static Web Apps, starting with an introduction to SWA and continuing on to building, enhancing, and deploying, your SWA for users to experience. Let's get started today by Introducing Static Web Apps.

What We'll Cover​

• What is Azure Static Web Apps?
• How is it architected?
• Where can I use it?
• 10 Key Features to know
• Exercise: Explore SWA Examples!
• Resource: Static Web Apps Overview

What is Azure SWA?​

Azure Static Web Apps is a cloud-based service that automatically builds and deploys full-stack web apps to Azure directly from your code repository. The service works with popular code sources like GitHub, GitLab and BitBucket by default. Look for the Deploying SWA post later this week where we walk through the details here.

The benefit to you as a developer is that it simplifies your developer experience. Just commit changes to your application source code into the repository and step back. The SWA service monitors the codebase for changes, automatically rebuilding and redeploying your app to the hosted endpoint. Look for a Previewing SWA post later this week where we'll talk about built-in support for previewing apps in non-main branches, or in pull requests, that make it easier to manage apps with multiple contributors.

Prefer a 5-minute video overview? We have you covered!

How is it Architected?​

Static Web Apps can be built using popular front-end frameworks including React, Angular, Vue, Svelte, or Blazor. These apps typically consist of a collection of static content assets (HTML, JS, CSS and media files) coupled with a dynamic API endpoint to handle client interactions in real time.

Traditional web application deployments use a single web server to serve both the static assets and the API endpoint. This can make scaling these services sub-optimal in terms of global availability and runtime costs.

With Static Web Apps, we separate static assets from API endpoints, allowing each to be scaled using the technology best equipped to do this in a cost-effective manner.

• Static assets get served from geographically-distributed content servers worldwide, distributing the load and speeding up access to users nearby.
• API endpoints are hosted using a serverless architecture, spinning up compute resources (to execute functions) only as needed, in response to trigger events.

This architecture - with static content servers, serverless backends, and automated CI/CD workflows - simplifies your development workflow allowing you to focus your attention on the application logic and user experience components of your modern web application.

Where can I use it?​

That's a great question!! You can use Static Web Apps to:

• Build modern web apps with front-end frameworks (like Angular, React, Vue etc.)
• Publish static web sites (using Gatsby, Hugo, Astro, Docusaurus, VuePress etc.)
• Deploy web apps with frameworks like Next.js and Nuxt.js.

You can configure your existing application to use Azure Static Web Apps using an IDE like VS Code, or using Command-line tools (like Azure CLI and SWA CLI), or through the browser (using the Azure Portal). Look for two posts later this week that dive into this in detail:

• Building SWA (tomorrow) on getting started with using SWA in your app.
• Configuring SWA (later) on customizing app behaviors and build process.

But wait - there's one more thing.

Keep an eye out for an announcement later in the series where we'll be debuting a new Community Showcase page - here's a sneak preview. You can filter it to see examples from popular front-end technologies, select "open source" to see the repository for inspiration - and consider adding your own project at the end of your journey!

10 Things To Know!​

We've talked about what SWA is, how it's architected, and where you can use it. But what are the key features that make it powerful? Read the Documentation for the detailed list - or scan the visual guide below for a summary!

Exercise:​

That was a lot to digest right? It helps to see some of these ideas in action. So here's two things you can do before we dive into the quickstart tomorrow:

• Visit the Showcase Gallery repository to see some examples of SWA in Action.
• Follow the #staticwebapps tag to see community-posted articles on usage.

Yesterday we got a quick introduction to Azure Static Web Apps (what it is, how it's architected, and 10 features that make it useful to modern web developers). Today, it's time to dive to dive into Building Static Web Apps.

What We'll Cover​

• How can I get started with SWA?
• Using SWA with personal and production projects.
• Building & Deploying your first SWA
• Tutorial Let's Build a Classic Movie Crawler!
• Exercise Your turn! And #MayThe4thBeWithYou
• Resources: Static Web Apps Quickstarts

1. Getting Started​

The Azure Static Web Apps service makes it easy to publish your modern web application directly from its codebase. Let's walk through that process for a basic web application (HTML, CSS, JS) first, to understand the development workflow and configuration options.

1.1 Requirements​

To do this quickstart, you'll need

• a GitHub account - you can signup for a free one if needed.
• an Azure account - you can signup for a free account to start.
• Visual Studio Code and this VS Code Extension - if you favor IDEs.

This approach assumes you favor using an IDE for development, and want to streamline build/deploy into that workflow. I'm a fan of Visual Studio Code so I'll use this approach. If you prefer to use the command line, or a browser, we have you covered!

• Quickstart: With Azure CLI - for commandline-driven workflow.
• Quickstart: With Azure Portal - for browser-driven workflow.

1.2 Final Outcome​

The goal is to take this basic HTML/CSS/JS application and configure it for automatic build/deploy to Azure Static Web Apps. We'll be using this official quickstart which comes with a vanilla-JS application starter template that provides our base application. Feel free to be adventurous and follow these steps with your own vanillaJS codebase.

We'll clone that starter first - making GitHub our default code-hosting provider. Azure Static Web Apps has flexible deployment options so look at tutorials for BitBucket, GitLab or Azure DevOps if preferred. Watch for the Deploying SWA post later this week for more details.

So what does that vanilla-JS starter app do? Not much - it's just a simple title on a blank webpage as shown above. Here's what you'll end up with when done:

• Hosted SWA: See the live-deployment here
• Codebase: See the code source repo here

Ready to do this? Let's go!

1.3 Build Process​

The process is captured in this quickstart document and has the following steps:

• Click to generate your vanilla-js app from the template.
• Clone the repo to your local machine. Open in Visual Studio Code.
• Install the Azure Static Web Apps extension in VS Code (if not present)
• Select Azure in the Activity Bar to view Azure Extensions window. You will be prompted to log into Azure and GitHub during this workflow if needed.
  1. Select the Static Web Apps section and click "+" to start SWA setup
  2. Select the relevant Azure subscription to use
  3. Select the region to deploy to (close to you)
  4. Select the "Custom" preset - use /src as app location, leave build empty
  5. Press Enter. Watch for a pop-up notification of build status.

Once deployment completes (you should see the success notification), visit the Azure Extensions window again.Look for the project in the Static Web Apps section and right-click for options. Here are three key ones to know:

1. Browse Site - click to see the live-deployed site
2. Edit Workflow - click to see automated GitHub Actions setup for the SWA.
3. Open in Portal - click to manage the SWA in the Azure Portal.

That's it!! You just deployed your first Static Web App with just a few clicks and configuration inputs! 🎉

1.4 Let's Unpack​

So what happened under the hood?

If you look at your codebase you'll see one key change - the Azure SWA service sets up the GitHub Actions workflow for you, directly in the repo using your GitHub credentials. No manual steps needed from you!

The workflow automates the build/deploy process on both code commit (push) and contribution (pull request) events. So when you make changes to your application code, it triggers the workflow to automatically rebuild and deploy the updated Static Web App. 🙌🏽

1.5 Video Tutorial​

Want to see a video walkthrough of the process? Check out this 2-minute Azure Static Web Apps: Tips & Tricks video from 2021. It features a different vanilla-JS application but follows the same "Quickstart with Visual Studio Code" steps so you can see them in action!

2. "There is No Try!"​

You realize today is May 3rd, right? That means tomorrow is May 4 - and what better way to celebrate our favorite movie call-to-action (MayTheFourthBeWithYou) than to pay homage with our own custom crafted movie banner sharing our origin story.

Try out this 3-part tutorial to take the basic HTML/CSS/JS application to the next level - and recreate the iconic introduction from the classic Star Wars franchise. Just do the thing!

1. Part 1: Create basic page and style it with HTML/CSS
2. Part 2: Bring moving banner to life with JS
3. Part 3: Use Visual Studio Code to deploy to Static Web Apps

Please Note: The tutorial is meant only to illustrate the creation of the banner with CSS/JS/HTML and celebrate an iconic movie on an iconic date! The movie logo, music and other iconic elements remain the property of relevant copyright holders and should not be used without permission.

3. Let's Talk Plans!​

The Azure Static Web Apps service comes with two plans - a Free plan that is perfect for Personal projects, and a Standard (paid) plan that is more appropriate for apps deployed in production. Check out the Features Comparison to judge what plan is best for you.

My personal experience is that, as an individual developer, the free tier is sufficiently generous to explore ideas and host prototypes (for real-world users) or demos (for validating ideas). The free tier also comes with Managed Functions support (to integrate a serverless API capability) out of the box. You will need the Standard plan if you want to "Bring your own functions" instead. For the most part, you should be able to try out all the Exercises in #30DaysOfSWA using the Free tier.

4: Exercise​

If you followed along with the quickstart, you should have setup and deployed your first Azure Static Web App using a vanilla-JS starter. Now, time to challenge yourself by trying out one (or both) of these options:

• Complete the other quickstart tutorials - using Azure CLI and Azure Portal - to get a sense of how the workflows differ. And join the #SWAanniversary event to learn more about SWA CLI for local development.
• Build your own movie crawler - follow Glaucia's tutorial to have the default banner running on Azure Static Web Apps - then customize the words to suit your origin story and share it on May 4th (StarWars Day) - and MayThe4thBeWithYou!.

Yesterday, we built and deployed our first Static Web App (using a vanillaJS template) from a GitHub repo. We used the VS Code Extension and, with just a few clicks, it setup automated GitHub Actions (CI/CD) workflows for us transparently. Today - we learn how we can add serverless API endpoints to our application using Azure Functions, helping us scale APIs more effectively with demand.

What We'll Cover​

• Why go Serverless with SWA?
• Add API with Azure Functions
• Quickstart: Use Managed Functions
• Bring Your Own Functions
• Example: Bring Azure-SWAG to May 4!
• Exercise: Try it out yourself!

Why Go Serverless?​

When Introducing SWA, we talked about how static web apps are architected to separate static content assets and dynamic API endpoints into separate components that can be served and scaled independently.

In yesterday's post we looked at a basic Static Web App with just content assets (no API). Deploying it with SWA helped us take advantage of Azure's globally-distributed content servers for fast and cost-effective access. Today, we want to add an API endpoint to support dynamic requests from clients. So what does serverless mean, and how do we implement serverless API endpoints?

In this context, Serverless is about using an event-driven architecture to allocate our compute resources on-demand. So, our API server will scale as demand grows, but be cost-effective when demand drops.

Azure Functions makes implementing your serverless solutions easier. Event handling is implemented with functions (code blocks) that run on compute resources that are dynamically-allocated. Resources can spin up as API requests grow, and spin down as demand drops. Try this learning path for a deep-dive into using Azure Functions.

Use Azure Functions​

Static Web Apps and Azure Functions are integrated seamlessly, enabling key features with respect to security (user data) and routing integrations:

• User data access - API functions can directly access user authenticaton and role-based authorization data when handling requests.
• API Route access - the application can access the /api route securely, without requiring custom CORS rules.

But it gets better. Your SWA can be configured for Azure Functions in two ways:

• Managed Functions - where the Azure Static Web Apps service configures and manages your Azure Functions deployment.
• Bring Your Own Functions - where you use a pre-existing Azure Functions application and manage the deployment yourself.

The Free plan supports only the Managed Functions option. It has some limitations - e.g., supports only HTTP triggers and lacks support for Durable Functions etc. - but is quick to setup and seamless to use. We'll explore this option today but look for a post in Week 4 that will discuss the Bring Your Own Functions approach in detail.

Adding the API​

Want to get some hands-on experience with adding an API endpoint to your Static Web Apps deployment? Check out this Quickstart tutorial that builds on the vanilla-JS application you deployed previously. The key steps are:

1. Setup Azure Functions for SWA

• Install the Azure Functions Extension for VS Code.
• Open your application root folder ("/") - create an "api" subfolder
• Select "Azure Static Web Apps: Create HTTP Function" through Command Palette or select the lightning bolt option in Azure extension menu.
• Enter required configuration information (language="JavaScript", function name="message"), and confirm.

Sit back and wait till the process completes setup. This populates the /api directory with configuration files (*.json) in the root folder, and a /api/message subfolder that contains 2 files:

• function.json - defines this function's trigger, bindings and other settings.
• index.js - implements an async function (accessed at /api/message)

2. Update the index.js file to implement your function - making sure it returns a desired response given the incoming API request and context (input parameters).

3. Update your application code to invoke the API - you can do this by calling fetch('/api/message') directly - the seamless Azure Functions integration ensures that the API routing happens automagically.

4. Test the integration locally with the SWA CLI. The Azure Static Web Apps CLI (SWA CLI) is a tool to support local development for Static Web Apps by emulating required services where needed. Follow these steps to install the tools and run/test your app and API together in your local development environment. Look for a detailed 2-part post in Week 3 ("Developer Tools") where we cover the SWA CLI capabilities, configuration, and usage, in more detail.

5. Update the GitHub Actions workflow with API location

This is the key step to make sure the Azure Static Web Apps deployment workflow also picks up the new API function.

• Open the default GitHub Actions workflow file for your SWA and update the api_location property to "api".
• Save and commit changes to trigger rebuild and deploy.

Want to see API in action? Scroll down to the Exercise section where we walk through a quick activity you can do to build and deploy a Static Web App with GitHub (SWAG) and celebrate #StarWars Day in the process!

Prefer a video tutorial? Check out this Azure Static Web Apps: Tips & Tricks that walks through the process from a react-starter template, and showcases the use of remote development container for Visual Studio Code that further streamlines your development experience.

Exercise: SWAG!​

Today is May 4 - Star Wars Day! Wouldn't it be nice if we could celebrate this with our favorite Star Wars quotes? Thankfully, my colleague Yohan has a great Azure-SWAG template that combines images from Unsplash with a pre-defined set of quotes in an API function ("/api/quote")

So I created a version for my May 4 homage. Here's what that looks like when deployed. Refresh the SWA to get a new image and quote each time (from the API).

• See the Code Repository
• See the Deployed SWA

Your assignment: follow these steps to replicate my project, then explore the index.js code to see how the /api/quote function is implemented and review the app.js code to see how that API is invoked within the application.

Useful Resources​

• API Support in SWA
• Add API with Managed Functions
• Bring Your Own Functions
• May4-Swag Demo

In the past two days we've seen how the Azure Static Web Apps services sets up default CI/CD actions (to automate build/deploy workflows) and transparently configures application to access the API with minimal input from us during setup. But what if we want to customize the build process or application behavior? That's where knowing SWA configuration options can help.

What We'll Cover​

• Configuration: Concepts & Files
• Customize: Application Behavior
• Customize: Build Process
• Customize: Environment Settings
• Exercise: Explore an open source app to see these in action!
• Resource(s): Links for deeper-dives into the topic

Concepts & Files​

When we think of configuring the Static Web App, we have three potential targets we can customize:

• Application: Use the staticwebapp.config.json file (located in the folder specified for app_location) to define rules and properties that customize application behaviors like routing, authentication, networking and more.
• Build: Static Web Apps automates your build/deploy workflow using GitHub Actions or Azure Pipelines, configurable via the relevant YAML files. For example, this would be the .github/workflows/azure-static-web-apps-xxx.yml file in your repo, for GitHub Actions.
• Environment: Sometimes configuration values may only be known at runtime - e.g., database connection strings. By using environment variables, you can update the values at runtime without having to change the application code that uses them. Environment variables can be set in the Azure Portal (for production) or in local settings files (for development.)

Let's take a quick look at what each of these provides, along with resource links for deeper dives that you can explore on your own. Check out the example scenarios to get a better understanding of which file (or concept) you need to focus on, for specific scenarios.

Config: Application​

Application behavior is configured using the staticwebapp.config.json file located in the folder defined by app_location. Here are a subset of the properties and their purpose:

• "routes" - are an array of "route" objects that can each be associated with access rules ("allowedRoles"), actions ("redirect", "rewrite") - and request ("methods") and response ("headers","statusCode") properties.

• "navigationFallback" supports applications that rely on client-side routing by providing a server-side fallback route which serves the required page, with filters to control usage.

• "responseOverrides" allows you to return a custom response instead of default HTTP error codes, for more user-friendly experiences.

• "platform" sets platform-specific configurations like apiRuntime for API language runtime version.

  There are also configuration properties for authentication, networking, global headers, custom MIME types and more. Check out the documentation for the complete list and scan this example staticwebapp.config.json to understand how these are defined.

{
  "routes": [
    {
      "route": "/profile*",
      "allowedRoles": ["authenticated"]
    },
    {
      "route": "/admin/index.html",
      "allowedRoles": ["administrator"]
    },
    {
      "route": "/images/*",
      "headers": {
        "cache-control": "must-revalidate, max-age=15770000"
      }
    },
    {
      "route": "/api/*",
      "methods": ["GET"],
      "allowedRoles": ["registeredusers"]
    },
    {
      "route": "/api/*",
      "methods": ["PUT", "POST", "PATCH", "DELETE"],
      "allowedRoles": ["administrator"]
    },
    {
      "route": "/api/*",
      "allowedRoles": ["authenticated"]
    },
    {
      "route": "/customers/contoso*",
      "allowedRoles": ["administrator", "customers_contoso"]
    },
    {
      "route": "/login",
      "rewrite": "/.auth/login/github"
    },
    {
      "route": "/.auth/login/twitter",
      "statusCode": 404
    },
    {
      "route": "/logout",
      "redirect": "/.auth/logout"
    },
    {
      "route": "/calendar*",
      "rewrite": "/calendar.html"
    },
    {
      "route": "/specials",
      "redirect": "/deals",
      "statusCode": 301
    }
  ],
  "navigationFallback": {
    "rewrite": "index.html",
    "exclude": ["/images/*.{png,jpg,gif}", "/css/*"]
  },
  "responseOverrides": {
    "400": {
      "rewrite": "/invalid-invitation-error.html"
    },
    "401": {
      "redirect": "/login",
      "statusCode": 302
    },
    "403": {
      "rewrite": "/custom-forbidden-page.html"
    },
    "404": {
      "rewrite": "/404.html"
    }
  },
  "globalHeaders": {
    "content-security-policy": "default-src https: 'unsafe-eval' 'unsafe-inline'; object-src 'none'"
  },
  "mimeTypes": {
    ".json": "text/json"
  }
}

Config: Build​

Azure Static Web Apps build workflows are powered either by GitHub Actions (in a file named something like .github/workflows/azure-static-web-apps-xxx.yml) or by Azure Pipelines (using the azure-pipelines.yml file).

The main settings you need to be familiar with are:

• app_location - folder for application source code
• api_location - folder with API functions source code
• output_location - where are build files generated
• app_build_command - custom app build command (for Node.js apps)
• api_build_command - custom api build command (for Node.js apps)
• skip_app_build - flag to skip app build step (if true)
• skip_api_build - flag to skip api build step (if true)
• build_timeout_in_minutes - defaults to 15 (customize to extend)

Read this document to learn how each of those properties can be customized and used effectively.

Config: Environment​

Your application behavior configuration values may change based on the runtime context. By setting values in environment variables, you can decouple definition of values from their usage within application code. We refer to these environment variables as application settings which are copied to both staging and production environments.

But where are they defined? That depends on the development stage:

• Local Development: When developing your app, you can use a local settings file that is not tracked by GitHub so sensitive information is not leaked. Azure Functions uses the api/local.settings.json file to store relevant app settings - and watch out for a special 2-part series of posts in Week 3 where we cover the local settings file used by the Static Web Apps CLI for a simpler, unified local development experience.
• Staging/Production: You can define and configure these application settings in the Azure Portal via the browser, or by using the Azure CLI (see the az staticwebapp appsettings documentation), to create and manage your application settings. These will be encrypted, and copied to staging and production environments.

Learn more about how you can configure application settings in the documentation.

How-Tos: Watch It!​

Want to see how application behavior configuration in action? Check out these two videos from the Azure Static Web Apps: Tips & Tricks series.

Exercise: Explore It!​

The SWA Bank is a Static Web App application developed as a solution for one of the projects in the Web Dev For Beginners curriculum.

It was recently updated to reflect best practices. Explore the configuration files in the project - and see if you understand how they customize the application behavior and build process. Then revisit it in week 3 when we discuss developer tools to understand how local settings are configured and used with the Static Web Apps CLI (swa) tool for local development

Useful Resources​

1. Configuration Overview
2. Application Configuration: staticwebapp.config.json
3. Build Configuration: Actions or Pipelines YAML
4. Environment Configurations: For Backends
5. Configure Application Settings
6. SWA Bank Repo - a Static Web Apps project to explore and learn from.

So far, we've learnt to build/deploy a basic web app, add a serverless API endpoint and customize the configuration settings for both application behaviors and build workflows. But we forgot one thing - the user! To create differentiated experiences for users, we need ways to identify them and understand their role in the application context. We can then use that information to manage user access to application features (role-based authorization) as well as application access to user information (once authenticated).

Thankfully, Azure Static Web Apps makes this fairly painless. Let's see how.

What We'll Cover​

• How do we secure a SWA?
• Managed authentication
• Custom authentication
• Managing user roles
• Role-based authorization
• Accessing user information

Securing SWA​

What does it mean to secure a Static Web App? It's three things:

• Knowing User Identity - Having a way to determine the identity of the user using an authentication service or provider.
• Knowing User Roles - Understanding what persona the user is taking on when (using the application), and customizing the experience accordingly.
• Managing User Access - Making sure the authenticaton information is seamlessly accessible to all SWA components, allowing them to enforce rules that allow only authorized users or roles to access resources.

Let's dive into the three concepts that tackle these needs: Authentication, Role Assignment and Role-Based Authorization.

Managed Auth​

Azure Static Web Apps comes with a default streamlined authentication experience that supports:

• pre-configured providers: Twitter, GitHub, Azure Active Directory
• pre-assigned roles: anonymous (guest) or authenticated (on login)
• customizable rules: defined for routes, in staticwebapps.config.json

All pre-configured providers are active by default, with their own pre-defined API endpoints for Login, and a shared API endpoint for Logout.

• Want to block a specific pre-configured provider? Just add a blocking rule to their login route to ensure no user is allowed access to it.
• Want to send users to custom pages after successful or failed login attempts? Use query parameters and route rules to make this work.

This is the default managed authentication experience.

Custom Auth​

But what if you want more flexibility with the registration process (used by a pre-configured provider) or want to add a new one (custom provider)? This is where custom authentication options come in, allowing you to override the defaults.

You can configure one or more custom providers for this purpose. Azure Static Web Apps has built-in support for custom authentication using: Apple, Facebook, Google, Twitter, GitHub - and AAD! You can also configure custom providers that support OpenID Connect standard.

By configuring at least one custom provider, you are effectively disabling pre-configured provider options. To configure custom providers, add config information to the auth section of the staticwebapps.config.json file. This is also a good place to use Application Settings (environment variables) to store potentially sensitive configuration data in a privacy-preserving way.

Azure Static Web Apps makes custom registrations easy by providing standard route patterns for Login, Logout and User Profile requests, as well as redirect URLs for authentication callbacks (from the custom provider) on login/logout.

User Roles​

There are three key concepts you need to know in this context:

• Every Static Web Apps user has one or more roles assigned to them.
• There are 2 built-in roles ("anonymous" and "authenticated")
• Define custom roles & assign users by invitation or by-function.

Let's review these quickly.

• All users accessing a Static Web App are in an anonymous role (guest) until authenticated by a pre-configured or custom provider.
• Once authenticated, they have an authenticated role but can now be assigned custom roles by invitation (proactive) or by function (reactive)
• Proactive invitations can be configured and sent from the Azure Portal, using provider-specific email addresses for the user. Users now click on the invite link to login with that custom role assigned automatically.
• Reactive functions defer assignment to post-login, using an Azure Function that dynamically returns an assigned role (or roles) to the user on being given the authenticated user details.

The latter approach offers more flexibility, allowing you to use the function handler to invoke another service (like Microsoft Graph) to make the role-assignment decision for you. Read Role Management for more details - including steps to update role assignments or remove users from a role.

Role-Based Auth​

Once the user has been assigned a role, managing user access based on that assignment becomes easy using the built-in support for routing rules based on the allowedRoles property attached to each route. For example, the following configuration setting (in staticwebapps.config.json) would restrict access to all routes that start with /profile* to only authenticated users. )

{
  "route": "/profile*",
  "allowedRoles": ["authenticated"]
}

Read more about securing routes with rules to understand various usage scenarios and configuration settings to enforce them.

Access User Info​

One of the benefits of Azure Static Web Apps' seamless integration of application and API capabilities is that authenticated user information can be accessed transparently in two ways:

• Using a direct access endpoint at /.auth/me that is automatically provisioned with the user's information when authenticated.
• Using API functions with a fetch call to the /api/xxx endpoint, where xxx is a named function you implement to return user information.

How-Tos: Watch It!​

Prefer a Video Walkthrough to understand the process? We have you covered with the Azure Tips And Tricks: Static Web Apps series. Check out the following videos:

Exercise: Try it!​

One popular feature that modern web apps often support is the ability to assign a custom role to an authenticated user (based on some identifiable context) and then regulate their access to various routes or features in the application based on that assigned role. How can we make that happen in Static Web Apps?

There's a tutorial that teaches you how!

• Authenticate the user using the managed Azure Active Directory API endpoint.
• Query Microsoft Graph to determine their Active Directory group membership.
• Use that membership to assign them a custom role.

Challenge Yourself!

Update the application behavior in the staticwebapp.config.json file to restrict user access to specific routes by specifying allowedRoles for those routes. Test what happens when the custom role above is added, and then removed, from the collection of allowedRoles.

Useful Resources​

1. Authentication and Authorization in SWA
2. Accessing authenticated user information in SWA
3. Implement custom authentication in SWA
4. Tutorial: Assign custom roles using Microsoft Graph and AAD
5. Video Series: Azure Tips And Tricks - Static Web Apps

We're almost at the end of week 1!! 🎉

So far, we've learned how we can use the static assets hosting (Azure Static Web Apps) and serverless API (Azure Functions) capabilities to build and deploy a web application in a scalable and cost-effective way. And we learned to configure and secure our Static Web App to suit our needs. So what else do we need to talk about?

Deployment options? Let's do it!! We've talked about the default experience so far: deploy from a production branch, using GitHub Actions for CI/CD. But how do we handle previewing the Static Web App before production deploys? Let's talk about previewing SWA in pull requests, on non-production branches, and in pre-configured named environments that make our staging workflows more productive.

What We'll Cover​

• What types of deployment does SWA support?
• Previewing: in Pull Requests
• Previewing: in Non-Production Branches
• Previewing: in Named Environments
• Deploying: to Custom Domains
• Exercise: Review PR using SWA Preview Capability

Deployment Types​

When we think about deployment, we are typically thinking of two kinds of environments: production which serve as the primary endpoint for real world use, and staging that can be used for internal testing, early validation of preview releases.

Azure Static Web Apps has built-in support for four types of environments:

• Production: This is the real world deployment endpoint that is indexed by search engines, and associated with the custom domain (if configured).
• Pull Request (PR): This is a temporary environment setup for a Pull Request, and torn down when that PR is closed.
• Branch: This is a environment you can set up for non-production branches, at a stable URL for the lifetime of the branch.
• Named: The above environments have URLs that reflect their PR (number) or branch (name). You can also configure a stable preview environment with a fixed name, associated with some deployment context (e.g., an interim release)

Production deploys have URLs like <DEFAULT-HOSTNAME>-<NUMBER>.azurestaticapps.net where the DEFAULT-HOSTNAME is unique for each application.

With preview environments, the URL looks like: <DEFAULT_HOSTNAME>-<BRANCH_OR_ENVIRONMENT_NAME>.<LOCATION>.azurestaticapps.net where the LOCATION reflects the deployment region, and the BRANCH_OR_ENVIRONMENT_NAME can also take the form of a branch name, a named environment, or a number in the case of pull requests.

Let's take a brief look at each of these.

Pull Requests​

Currently Pull Request preview environments are available for projects hosted in GitHub, and configured to use GitHub Actions by Azure Static Web Apps:

• Every PR to a watched branch gets a dedicated but temporary pre-production staging environment that is torn down when the PR is closed.
• Use it to validate changes, perform sanity checks, etc.
• The environment is automatically rebuilt and deployed if new commits are made to the branch associated with an active PR.
• The staged environment is publicly visible event if your GitHub repo is private - though the URL is not easily discoverable (i.e., not indexed by search engines) by default.

Learn how to preview Pull Requests in Azure Static Web Apps.

Branches​

Preview environments for branches will have stable URLs. Configure them in the relevant GitHub Actions or Azure Pipelines workflow files as shown in this example.

For example, in a GitHub Actions context, this involves two steps:

• set the production_branch property to the branch you want to use as the source for that production deployment.
• list all other branches that you want preview environments for under trigger (Azure Pipelines) or push: branches (in GitHub Actions).

You can use a wildcare (** for GitHub Actions, * for Azure Pipelines) if you want to track all branches for preview environment support.

Here's an example GitHub Actions config file - the production environment is built from the main branch, and separate preview environments are built for the other listed branches (dev and staging).

Learn how to create branch preview environments in Azure Static Web Apps.

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
      - dev
      - staging
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main

jobs:
  build_and_deploy_job:
    ...
    name: Build and Deploy Job
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          ...
          production_branch: "main"

Named Envs​

Sometimes, you want to have a non-production preview environment that is at stable URL (not tied to a specific PR number or branch name), and that gets rebuilt on commits to all tracked branches in the configuration file.

Just like with branches, this requires a manual change to your default configuration file (GitHub Actions or Azure Pipelines) as shown in this example.

In the GitHub Actions case, the steps are:

• Set the deployment_environment property (in the relevant build job) to be the name you want to use for this preview environment
• List the branches you want associated with this named environment under push: branches - commits to those will result in rebuild/deploy to this environment.

Here's an example GitHub Actions configuration file - this sets up a named environment called release which gets updated when changes are made to any branch (reflected by the ** wildcard), and deployed to a site with a URL like <DEFAULT_HOST_NAME>-release.<LOCATION>.azurestaticapps.net.

Learn about named preview environments in Azure Static Web Apps

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - "**"
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main

jobs:
  build_and_deploy_job:
    ...
    name: Build and Deploy Job
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          ...
          deployment_environment: "release"

Custom Domains​

You may have noticed that default deployment URLs - in the form XXX.azurestaticapps.net for production environments or XXX.<LOCATION>.azurestaticapps.net for preview environments - are not exactly user friendly for use and recall.

Adding a custom domain helps. Azure Static Apps makes that easy with options to also configure subdomains and an apex domain! Here, given a domain like www.azure.com, azure.com is the apex domain and www is the relevant subdomain.

So how do you configure these? You have two options:

• Use an external DNS Provider (if your domain registrar supports it)
• Use Azure DNS (to manage your DNS domain, even if purchased elsewhere)

To keep this post short, we won't go into details for each of these options. Instead check out these links based on the direction you want to go in:

• Setup Apex Domain - with Azure DNS | with External Provider
• Setup Subdomain - with Azure DNS | with External Provider

How-Tos: Watch It!​

Prefer a Video Walkthrough to understand the process? We have you covered with the Azure Tips And Tricks: Static Web Apps series. Check out this video to understand how you can setup a custom domain for your Static Web App!

Exercise: Try it!​

Pull Requests are critical to having a productive open source or multi-contributor project, so it's important to know how Azure Static Apps works in setting up pre-production environments for validating the changes proposed in a pull-request, before merging it for production deployment.

Get hands-on experience with the process by completing this tutorial on an existing Azure Static Web Apps project.

At present, the staged pre-production environment for Pull Requests is available only for GitHub Actions deployments - so make sure you pick a GitHub-hosted SWA project that already had the default workflows set up.

Useful Resources​

1. Preview environments in Azure Static Web Apps
2. Pull-Request Preview Environments
3. Branch Preview Environments
4. Named Preview Environments
5. Video Series: Azure Tips And Tricks - Static Web Apps
6. About Custom Domains

You made it this far! Give yourself a pat on your back already! 😊

By now, we have learnt what Static Web Apps is, and how to build, add APIs and configure the application. We’ve also deployed a couple of fun apps as a tribute to Star Wars! But we’ve so far explored deploying using the Github Actions path.

• What if we want some other CI/CD tool?
• What if our project resides safely in an Azure DevOps repository?
• What if we don’t want a CI/CD solution AT ALL?

Fear not! Because today we’re gonna explore other ways of deploying a Static Web App on Azure 😊

What We'll Cover​

• Deploy With Azure DevOps
• Deploy From GitLab and BitBucket
• Deploy Using ARM Template
• Exercise: Explore the ARM Tools VS Code Extension

Deploy with Azure DevOps​

Deploying using Azure pipelines CI/CD has never been easier!

Static Web Apps supports projects which are stored in Azure repos and helps in creating a smooth CI/CD pipeline to automatically trigger the changes on every commit to the main branch. What more? With the latest changes checked in for Azure DevOps, we can now set up the azure pipeline via Portal with a single click! Here’s a quick video demonstrating how to use DevOps as a pipeline, as well as touching on the numerous other enhancements brought in off-late, such as stable staging environments, password protected websites, build and deploy split, and lots more! 😊

Deploy via GitLab and BitBucket​

But what if we wanted a third-party Provider? Static Web Apps as of today officially supports CI/CD pipelines from GitLab and BitBucket! We just have to follow a few simple steps as discussed in the documentation for both GitLab and BitBucket, and voila! We’ll have a beautifully configured pipeline which takes care of the automatic trigger on commits for us. Isn’t this beautiful? 😊

Deploy using ARM Template​

For the CLI lovers out there, we can also deploy in Static Web Apps using ARM Templates! The ARM - or Azure Resource Manager Template - is used in preparing the workflow template. On deploying the ARM Template to Azure Static Web Apps, it triggers the Github Actions, which further takes care of our CI/CD needs. Do check out the exercise later in the blog for a quick hands-on using ARM Templates!

But what about .. deploying without a CI/CD??

Suppose we want a one-time deployment solution? Or we don’t want to depend on a CI/CD tool at all! No worries! We have you covered! Wonder how that is supported? Stay tuned to the #30DaysOfSWA series and discover the new upcoming features to enable this! 😉 <3<3

Resources​

Now that we’ve explored the alternatives we have, let’s go have some fun with it!! Here are a few quickstarts you can try out!

1. Deploy using BitBucket
2. Deploy using GitLab
3. Deploy using Azure DevOps and Portal Quickstart
4. Use an ARM template quickstart

In Week 1 we covered core concepts for Azure Static Web Apps - from development to API-enablement, security, configuraton and deployment.

Today, we kick off Week 2 with a focus on seeing SWA in action - using popular web development frameworks and static site generators to build and deploy different kinds of applications. We kick things off with a look at Astro - a modern static site generator with a BYOF ("Bring your own framework") approach.

What We'll Cover​

• What is a static site generator?
• What is Astro?
• Build & Deploy a Personal Blog with Astro
• Exercise: Try the tutorial to deploy your personal blog!

Static Site Generators​

The term "static site generators" (SSG) refers to tools that automatically build static webpages for you, populating a chosen template with your custom content or data. The code generation is transparent to you, making it possible for even non-developers to setup custom static websites quickly.

Static site generation is a growing trend for fast, flexible website creation. But it requires an external service to handle hosting and build/deploy workflows. This is where Azure Static Web Apps comes in! Check out the SWA documentation for tutorials featuring popular SSGs like Hugo, Jekyll and Gatsby. We'll explore some other examples later this week.

Hello, Astro!​

Today's post will however focus on Astro, one of the rising stars of JavaScript in the Static Sites category. Astro is a static site builder that works like an SSG but with some novel features that set it apart.

• Bring your own framework (React, Vue, Svelte, web components)
• Compose your website using that framework's UI components
• Astro now renders a fully-static (all HTML, no JavaScript) website

Astro emphasizes fast performance with less JavaScript - and takes a partial hydration approach that allows it to load the minimal required amount of JavaScript, if and when absolutely necessary. Here's a quick overview of Astro.

Astro + SWA​

In today's tutorial, we walk through the steps required to:

• create an astro-powered blog (using this template
• test it locally using the Azure Static Web Apps CLI (swa)
• deploy it using the Visual Studio Code Extenstion for SWA

The end result will look like this.

Here are the key links to know:

• Visit this page for the step-by-step tutorial.
• Check this repository for the source code (demo app template)
• See this site for the deployed version of the app.

Then check back tomorrow for a new usage example and tutorial - this time, with a focus on React - as we continue to explore Azure Static Web Apps in action!

Exercise​

Here are a couple of options to try, to get more hands-on experience:

• Clone the template project and follow the tutorial to build and deploy your personal blog.
• Visit the Astro Themes page and try using a different starter project, then deploying it to Azure Static Web Apps.

Resources​

Check out these other tutorials using more traditional static site generators:

• Publish a Gatsby site to Azure Static Web Apps
• Publish a Hugo site to Azure Static Web Apps
• Publish a Jekyll site to Azure Static Web Apps
• Publish a VuePress site to Azure Static Web Apps

Yesterday we looked at using a static site builder (namely Astro) to create a personal blog and host it with Azure Static Web Apps. Over the next two days, we switch gears and look at using Azure Static Web Apps with some popular front-end frameworks - starting today with React.

What We'll Cover​

• Why Learn React?
• React + SWA: Quickstart
• Build: Inventory Management App
• Exercise: Build & Deploy a basic React SWA.

Why Learn React?​

React describes itself as a JavaScript library for building user interfaces that targets single-page application (SPA) development with a declarative and component-based approach. Today, it's one of the most popular technologies used for web development, leading the 2021 rising stars of JavaScript section for front-end frameworks. Whether you're new to web development, or an experienced developer, it's a technology worth learning.

New to React? Here are a couple of resources:

• Official Tutorial: Intro to React
• Creating your first web apps with React - on Microsoft Learn
• Web Dev For Beginners - project-based curriculum

`

SWA Quickstart​

Once you have a simple React application scaffolded, configuring it to use Azure Static Web Apps is easy. In week 1, we covered the three different approaches (using Visual Studio Code, using Azure Portal, using Azure CLI) to build and deploy a vanillaJS app.

Want to try building and deploying a basic React starter app? The Azure Static Web Apps documentation has Quickstarts to help!

The following tutorials use the react-basic starter template bootstrapped using create-react-app. Pick an option based on your preferred development environment:

• SWA Quickstart: Using Visual Studio Code
• SWA Quickstart: Using Azure CLI
• SWA Quickstart: Using Azure Portal

This should help you setup and validate the basic tooling required for developing Azure Static Web Apps. Now, let's think about building something a little more functional!

Inventory Mgmt​

Today, I'm publishing the first of a multi-part tutorial on how you can build an inventory management app with Azure Static Web Apps and React.

Read Part 1 of the Tutorial Here:

In this series, I'll take you from the very beginning on generating a React app and deploying it within 5 minutes. In the upcoming parts, I'll keep building on the same app, and add things like backend and other things.

In this tutorial you'll learn about:

• Options to scaffold your React App
• Use the Snowpack option to scaffold your project
• Use VS Code to configure & deploy the app to SWA.

Check out the deployed SWA at this stage of the tutorial. In the next part of the series, we'll improve UI and add routing support.

Revisit this series page tomorrow to continue with the tutorial.

Exercise: Try It!​

This is the perfect time to make sure you have your development environment setup and ready to follow along. Try the quickstart option, then follow along with the tutorial series.

Resources​

Here are the key resources we shared in this article:

• SWA Quickstart: Using Visual Studio Code
• SWA Quickstart: Using Azure CLI
• SWA Quickstart: Using Azure Portal
• Official Tutorial: Intro to React
• Creating your first web apps with React - on Microsoft Learn
• Web Dev For Beginners - project-based curriculum

Vuelievers, rejoice! Today we'll explore several examples of how you can build a Static Web App with the Vue.js framework

In this article, I'll give several examples of sites I've created using Vue and VuePress, a popular way to build static sites with Vue. I'll also walk through a game engine we created in VuePress that you can deploy as a SWA, and touch on the use of Vite.js, a lightning-fast toolkit you can use to build all types of applications, built by the masterminds behind the Vue.js projects.

What We'll Cover​

Let's explore some creative application usage examples:

• PoseDance: with PlayFab
• Ombromanie: with TensorFlow.js
• Olympic App: with Vite.js
• Azure Mysteries: a static Game Engine
• Exercise: Build a game with VuePress, deploy to SWA!

In this article, I'll describe the following projects, which are more fully explained on their README files in their respective repositories. The first apps I'd like to showcase are PoseDance and Ombromanie. Both were developed as conference talks and have become interesting case studies in how to use TensorFlow.js in web apps, specifically focusing on body poses and hand poses for innovative user experiences.

1. PoseDance​

PoseDance is your friendly TikTok trainer: watch a TikTok dance video, learn the dance, then enter a side-by-side view of the original dance with a 'skeleton' imposed on it to the left, with your own video on the right. Try to make your body poses match that of the dancer, and win a high score!

PoseDance offers a full view of SWA capabilities, including an API buildout so that the user can login and save their high scores. To save scores, it also uses PlayFab in the backend. In addition this repo has a Code Tour!

Code Tour is a neat little Visual Studio Code extension that, if installed locally, will allow you to walk through the codebase in a guided manner, to learn the rationale behind code architecture. Install that extension in VS Code and give it a try!

Explore: PoseDance

• Watch the video about the making of PoseDance.
• Walk through the conference slides.
• Explore the codebase
• Visit the deployed site and Dance with us!

2. Ombromanie​

Ombromanie is a demo I built for a different conference talk that was described as "un peu OVNI" ("a little UFO-like"). In this demo, mimic the hand shadows that you used to make using just a candle and a dark room, to freak out and entertain your siblings.

Like PoseDance, this app is also built using Vue.js, and leverages TensorFlow.js and bodyposing - this time focusing on hand poses, which are actually more complex than body poses, as there are more bendable joints in play.

Use the Ombromanie app to record a video of your special hand shadow story, coupled with voice-to-text transcription of your story, and then share it.

Explore: Ombromanie

• Read the blogpost
• Watch the conference talk
• Walkthrough the conference slides
• Visit the deployed SWA and Create Hand Shadow Stories!

3. 2021 Olympics​

For the Microsoft Build conference in 2021, I wanted to demonstrate how to use Vite.js to build a simple 'card flipping' app. Since it was close to the Summer Olympics, I featured all the Olympic sports in this interesting interface. Building with Vite is similar to building with Vue, although the location of the files is different. But deployment as a SWA is just as straightforward.

Explore: Olympics App

• Visit the deployed SWA to see it in action.
• Watch this video and build the app with me!
• Explore the source and build it yourself!

To build it, start on the student branch and build up the app following the video instructions, or just look at the entire complete codebase.

4. Azure Mysteries​

Finally, and something really different, I'd like you to meet SpaceQuest, a game engine that I developed with inspiration and help from my colleague Chris Noring. SpaceQuest is a game engine you can use to build your own games, and deploy as a SWA, in the tradition of text-based point and click adventure games.

We used this engine as the core to build the Azure Maya Mystery and the Azure Space Mystery experiences, all deployed as SWAs to great acclaim. Learn more about these adventures here:

Explore: Azure Maya Mystery

• Introducing Azure Maya Mystery
• The Making of Azure Maya Mystery
• The Mysterious Cenote
• Ascent to the Summit

Explore: Azure Space Mystery

• Introducing Azure Space Mystery

SpaceQuest had a very special purpose, other than being the seed code of the mysteries, however. We used it in a series of workshops with Autistic students to teach them how to build their own games, in partnership with the National Museum of Computing at Bletchley Park.

• Learn about this work. It was a tremendous honor to work with these talented students!
• Try the deployed SWA
• Explore the source

Then build a mystery of your own by forking the codebase and building up your storyline - and share it with us!

Resources​

1. Vue.js - The Progressive JavaScript Framework
2. Vite - Next Generation Frontend Tooling
3. VuePress - Vue-powered Static Site Generator
4. Get Started with Vue - on Microsoft Learn
5. Publish a Vue App with Azure Static Web Apps - on Microsoft Learn
6. Tutorial: Publish a VuePress Site to SWA

Today's a special day - the 1 year anniversary of Azure Static Web Apps!
Happy Birthday SWA! 🎂

I wanted to do something special to celebrate - and I thought of just the thing! Let's create a content-focused static website with Docusaurus and deploy it using Azure Static Web Apps. Want to get a sense of what kinds of static sites you can build with Docusaurus? Check out their showcase!

Why this demo today? Well, it's very Meta (pun intended). You may have noticed that the #30DaysOfSWA website is built on Docusaurus. 🦖

By sharing this tutorial, I'm hoping it inspires more of you to build/deploy sites that showcase your own tech journeys - whether its with #30Days of learning, or to feature your #100Devs portfolios. #LetsGetStarted! 🎉

What We'll Cover​

• Intro: What is Docusaurus?
• Quickstart: setup classic site
• Configure: docusaurus.config.js
• Deploy: Azure Static Web Apps
• Customize: Themes & Plugins
• Exercise: Try extending the demo further

About the Demo​

In today's tutorial, we'll create a classic Docusaurus site, deploy it to Azure Static Web Apps, then make some changes to the site content to validate that it rebuilds and deploys the site without any further manual effort from us. I hope to also contribute this back to the Docusaurus docs as an example for Deploying to Azure - feedback to improve this is very welcome!

• 🌟 The tutorial source is here on GitHub - I'll update that version over time.
• 🎉 See the site live on Azure Static Web Apps - for demo purposes only.

What is Docusaurus?​

Docusaurus is an open-source project from Meta that helps you build, deploy, and maintain, open source project websites. It was rated one of the top 3 rising stars of JavaScript in 2021, under the static site generators category. It has a number of features that made it attractive:

• It has built-in support for search, localization and versioning
• It support MDX (JSX-flavored Markdown) for richer content options
• It has built-in support for themes and plugins to enhance default behaviors
• It is built with React, making it extensible with custom components

Read their documentation & visit their showcase to see real-world examples. Now, let's dive into our tutorial for building the demo.

1. Setup Site​

1. Setup a Docusaurus site (classic theme) in a dedicated folder (www) in repo. The command automatically installs the required packages and their dependencies.

 npx create-docusaurus@latest www classic

2. Let's see what was created for us. The output has been cleaned up for clarity.

ls -l www/

README.md   
babel.config.js 
blog/              
docs/    
docusaurus.config.js               
node_modules/        
package-lock.json    
package.json           
sidebars.js                 
src/                  
static/    

3. Let's preview the site locally, to validate this worked.

cd www
npx docusaurus start

[INFO] Starting the development server...
[SUCCESS] Docusaurus website is running at http://localhost:3000/.

You should see something like this - this is the default landing page for the scaffolded Docusaurus site.

4. The dev server supports hot reloading. Try making a minor change to the site source - for example edit docusaurus.config.js and change the title to "My Static Web Apps Site". You should see this in your site preview, instantly:

5. You can now build a production-ready version of that site as follows. Note that the static files are generated in the build/ directory.

cd www/
npm run build
..
..
[SUCCESS] Generated static files in "build".
[INFO] Use `npm run serve` command to test your build locally.

2. Deploy To Azure​

Docusaurus is built using React - so you can use the same configuration settings for Docusaurus, when deploying to Azure Static Web Apps.

You have three options to get started:

• via browser with the Azure Portal quickstart
• via terminal with the Azure CLI quickstart
• via IDE with the VS Code Extension quickstart

If you prefer the first approach, click the button to go to the Azure portal, then follow the quickstart guidance, but using this project's details instead.

3... using VS Code​

I'll use the Visual Studio Code extension to make this happen with just a few clicks.

The whole process happens within the VS Code window, and takes just a few minutes from start to finish - with guided prompts to help all the way. For convenience, I've documented it step-by-step with screenshots (images valid for VS Code ver 1.66.2).

3.1 Install Extension​

Open Visual Studio Code (IDE) in the project folder for your repo. Install the Azure Static Web Apps extension by visiting this page and clicking "Install".

3.2. Find SWA Panel​

When extension is installed, you should see this window in your VS Code editor, confirming readiness for use.

You'll find the Azure Static Web Apps options listed in a section under "Azure".

The extension's documentation page and its GitHub page both provide detailed walkthroughs - check those for the most current process for this. We'll start by clicking the Azure icon in the VS Code sidebar, then scrolling down till we see this Static Web Apps section.

3.3 Create SWA​

Click the "+" button to start the Create Static Web App workflow.

The "Create Static Web Apps" process will create (and commit) a GitHub actions workflow for you that will automate the build/deploy process for your site directly from your source on all future codebase changes.

So if you have current pending codebase changes it will first prompt you to commit them before it does its magic! Let's get that done!

3.4 Configure SWA​

The extension walks you through the five steps shown below, each with defaults already filled in for you. Customize them as shown, for this project:

Screenshot	Step
	Specify project name
	Pick Azure region to deploy it in
	Pick framework used by app
	Specify folder contaning site source
	Specify folder where site gets built by default

3.5 Track Progress​

In a few seconds, you'll see this alert - this indicates that the workflow is creating and committing the GitHub Actions build/deploy workflow YAML for you. 🎉

If you check your repository right now, you'll find the relevant commit and the activated Actions flow (labeled ci: add Azure Static Web Apps worfklow) in progress.

You can also track the progress and configuration settings of your app right there in the VS Code Sidebar, under the Static Web Apps section. Look for the project name, and unroll contents..

3.6 Browse Site!​

In a few second more, you'll get this alert:

Now, go to the sidebar section for your project, right-click the name to see the available menu options:

Click "Browse Site" to be taken to your live deployed Docusaurus website! That's it! A few clicks, customizing defaults - and you're done!

4. Customize It!​

At this point, you can make any changes to the site source, commit them - and watch the site get rebuilt and deployed without any further action from you!

Here are some things to try:

• Customize styles or layout
• Explore plugins for SEO, Search etc.
• Try create/use MDX in content

I made a few example changes to the docusaurus.config.js file to personalize the landing page content to reflect my needs.

And I updated the src/css/custom.css file to reflect new theme colors for dark/light mode - and replaced the logo.svg file.

Committing these changes should automatically rebuild and update the deployed site. Here is what they looked like in my local preview, before I committed the changes.

Light Mode	Dark Mode

🎉 Check it out: The site is live on Azure Static Web Apps

Exercise​

You saw a few things I did to customize the site. Now it's your turn! Here are a few challenges you can try out:

• Complete the tutorial to deploy your own site!
• Try Docusaurus customization: add an MDX component!
• Try SWA customization: add an API to fetch content!
• Try SWA customization: add auth using Twitter - use it!

Resources:​

• Docusaurus - documentation
• Azure Static Web Apps (SWA) - documentation
• #30DaysOfSWA - guide tour to SWA.

Over the last few days we've been exploring JavaScript-based frameworks for building web apps. Today, we switch our attention to our amazing .NET community and talk about building Static Web Apps with Blazor

What We'll Cover​

• Introduction: Blazor WebAssembly
• Quickstart: Simple Blazor SWA
• Advanced: Blazor SWA + Wordpress CMS
• Exercise: Remix Fritz's Hat Collection!

Blazor WebAssembly​

When we think about web applications, we typically think of developing with JavaScript, HTML, and CSS. In fact, many of you reading this series may identify yourselves as JavaScript developers when discussing modern web apps.

What if I told you that was not always the case? What if you could write web applications in C#, running in a .NET runtime inside the browser! Turns out you can - thanks to Blazor.

What is Blazor?

Blazor is a framework for building interactive client-side web UI with .NET. Developers can build interactive web applications using C# (instead of JavaScript) - and extend experiences to hybrid desktop and mobile apps with .NET capabilities.

What is Web Assembly?

Running .NET code inside web browsers is made possible by WebAssembly(wasm) - a binary instruction format and open web standard that is designed as a portable compilation target for programming languages. It provides a sandboxed runtime that can be implemented inside JavaScript virtual machines (like those in modern web browsers) to support web apps.

How does Blazor WebAssembly Work?

Blazor WebAssembly is a framework for building single page app (SPA) that works with all modern web browsers, including mobile versions. Blazor apps are written using Razor components in a .NET runtime. The .NET code is then executed via WebAssembly in the browser's JavaScript sandbox. WebAssembly uses JavaScript interoperability to get full access to browser features. Learn how Blazor web apps work.

Simple Blazor SWA​

Want to learn how you can deploy a simple Blazor application to Azure Static Web Apps? We have you covered! Follow this tutorial to learn how to deploy an existing Blazor app to Azure Static Web Apps.

The end result will look something like this - a single page Blazor web application that displays weather data returned from a serverless API - beginning with this starter app,

Blazor SWA and Wordpress​

Want to try a more complex example? Check out this advanced tutorial (from Justin Yoo). Here's a brief introduction:

One of the most popular scenarios to build a static website is to run a blog site for myself or my organisation. WordPress is the most popular service for this purpose. Now, you want to migrate your WordPress blog site to a static website, but it doesn't look easy.

What if you still want to use the WordPress site to write content but only want to refresh the UI outside the site? What if you can even use C# for it through Blazor WebAssembly? You are now able to use the existing WordPress site as the data source of truth and build a UI in a separate instance with your preferred method. Does that sound attractive?

Join Justin as he walks through the steps required to:

• use the serviced Wordpress instance as a headless CMS
• build the Blazor WebAssembly app using Wordpress
• host the completed app on Azure Static Web Apps

The end result issomething like this. Read the blog post behind this!!.

Exercise: Remix Fritz's Hats!​

Hopefully you're ready to try something fun that will reinforce what you learned today.

Say Hello to (Jeff) Fritz's Really Cool Hats

Fritz's Really Cool Hats is an open-source static web site built with Blazor WebAssembly, incorporating C# Azure Functions and Azure Storage, and deployed using Azure Static Web Apps. The project was created by Jeff Fritz - the face behind many Twitch livestreams and the popular Beginners Series To Blazor.

Visit The Deployed Site

For this exercise:

• Fork the repository and clone it locally.
• Open project in Visual Studio - press F5 to launch (app and api).
• Configure your Azure Storage account to add your own images
• Use the quickstart to deploy to Azure Static Web Apps.

Explore the source and the GitHub Actions files in the original repository to understand how the app is structured. Then share your deployed project with us by tagging a tweet with #30DaysOfSWA.

Resources​

Here are some resources to get you started with your Blazor journey into

• Blazor: Build Client Web Apps With C#
• Beginner's Series to: Blazor
• Tutorial: Build a Static Web App with Blazor
• Fritz.HatCollection - Source, Jeff Fritz
• Headless CMS Example - Source, Justin Yoo

Yesterday we talked about deploying Blazor apps on Static Web Apps. Let's continue today with one more type of the projects you can successfully host on SWA - Progressive Web Apps (PWAs).

What We'll Cover​

• How do I start with building a PWA?
• Optimized PWA-on-SWA configuration
• Advanced techniques for better user experience
• Exercise: Deploy your PWA on SWA, run offline, and install it

Progressive Web Applications​

A Progressive Web App (PWA) is a web frontend application that is progressively enhanced using open web technologies, to make sure it delivers the best possible experience on every device, based on available capabilities. The "baseline" for your app to have a title "progressive" is its installability and offline-readiness. We skip the "served with https" requirement because it became a baseline for any web app these days.

This chapter of #30DaysOfSWA assumes that you are familiar with the basic concepts of a Service Worker API and automating your service worker with the Workbox library. If you wish to learn about these technologies, you are welcome to go through the Core Concepts part of the #30DaysOfPWA project (see roadmap above) to learn about PWA fundamentals and to watch Automating a service worker with the Workbox 6 video for quickstart with Workbox.

Is hosting a PWA on Azure Static Web Apps different from "classic" apps?​

A Progressive Web Application is still a web frontend app so the initial scaffolding of your SWA resource is the same - you have learned how to deploy and configure various types of web apps from the previous chapters of the #30DaysOfSWA. But to make sure that your "PWA on SWA" works as intended both online & offline to provide the best possible user & developer experiences, you might need to pay special attention to some implementation details and fine-tune some configuration options. We'll go through the following points in this chapter:

• Building your service worker as a part of the overall app build
• Setting up HTML5 routing - for the Single-Page Application (SPA) use-case
• Applying caching strategies for SWA-hosted APIs
• Showing custom error pages
• How to deal with authentication in PWA

Sample project

I created a PWA on SWA Starter project with all the best practices implemented. The app is hosted on SWA as shown below. Let's explore it!

Technical stack:

• A React application scaffolded by the create-react-app tool. A simple SPA with a few routes and the possibility to call API endpoints. Note that the approaches described are applicable for any web frontend application: framework-based (including your custom frameworks) or "vanilla" JavaScript. We use React only for getting closer to the real-world scenario of the modern frontend app development when you have to perform some operations with your source code ("build the app") before the deployment.
• A service worker powered by the Workbox library.
• Two API endpoints created within SWA resource - to emulate "dynamic" (/api/news) and "conservative" (/api/archives) data sources.

Building your service worker as a part of the overall app build​

The service worker file we have in the src/sw folder of the application is not ready for the deployment. We have to

1. Process it by the workbox-build module to populate with the resources to precache (to provide offline-readiness)
2. Bundle it
3. Choose production or development mode
4. Minify for deployment

This is why in package.json's scripts we have "build-sw": "node scripts/sw-build.js && npx rollup -c" command that is building a service worker file and copies it into the app distribution folder.

By default, Azure Static Web Apps runs npm run build command to build your application. So do not forget to add a service worker build command there. The resulting command will be:

"build": "react-scripts build && npm run build-sw"

Instead of react-scripts build, there might be a command to build an application using a framework/bundler of your choice. Important: Keep this order - you always build a service worker after the main application because the distribution folder will be scanned to list the files to precache based on the pattern you provided.

Setting up HTML5 routing - for the Single-Page Application (SPA)​

For having correct navigation in your single-page application, you have to "ask" the webserver to redirect all navigation requests to index.html - to run the application and let it do the routing. In SWA, you have to have something like this in the configuration file:

"navigationFallback": {
  "rewrite": "index.html",
  "exclude": ["/images/*.{png,jpg,gif}", "/static/*"]
}

Best practices:

• Always "exclude" as much as possible in navigationFallback - it will help you to identify and fix "resource not found" errors.
• Do not copy staticwebapp.config.json to the app distribution folder - SWA will find it in any location within the app source code.

In case of PWA, there is an extra layer of this fallback: the first in a row to handle navigation requests is a service worker. In the service-worker.js we have to have the following block for correct routing in SPAs:

const navHandler = createHandlerBoundToURL('/index.html');
const navigationRoute = new NavigationRoute(navHandler, {
  denylist: [
    new RegExp('^/images/'),
    new RegExp('^/static/'),
  ],
});
registerRoute(navigationRoute);

The above configuration will work fine for opening both root url and "deep links" like /about both in online and offline modes.

Showing custom error pages​

It's a best practice to create and show custom error pages (for example for 404 Not Found) instead of the ones built-in in the browsers. And it makes sense to keep these pages as simple as possible - without running a SPA itself. To set up custom error pages, you add the following block to the SWA config

"responseOverrides": {
  "400": {
    "rewrite": "/400.html"
  },
  "404": {
    "rewrite": "/404.html"
  }
}

These pages will be excluded from SWA's navigation fallback automatically because these two html are in the app distribution folder. But for the Workbox and explicit directive needed - just add these addresses to the same denylist we met with the HTML5 navigation section.

Applying caching strategies for SWA-hosted APIs​

With Workbox, runtime caching is simple: you specify a url pattern to "listen" and intercept, and a caching strategy to apply. There are 5 strategies available and you can always create a custom one. By default, all API urls start with /api. Then in a service worker, we'll add this block for caching responses from our two API endpoints using different strategies:

registerRoute(
  ({ url }) => url.pathname.startsWith('/api/news'),
  new NetworkFirst()
);

registerRoute(
  ({ url }) => url.pathname.startsWith('/api/archives'),
  new CacheFirst()
);

Now, the data from APIs, once fetched, is also available offline!

Mini-exercise: Open the hosted PWA on SWA Starter, open the Network tab of DevTools, and click on two buttons in the "API caching" demo area. What difference do you see in the network request/response patterns for these two strategies?

How to deal with authentication in PWA​

A couple of important rules here:

1. Explicitly exclude the .auth system folder of SWA from Workbox's navigation fallback (use denylist) and never set up runtime caching for it
2. Never runtime-cache all data users fetch from restricted API endpoints (served by SWA or external)

And it's a best practice to never precache and always exclude from the service worker's navigation fallback all urls related to the user authentication and restricted parts of your application. Have a look at the resulting denylist of our sample application.

Exercise: Deploy your PWA on SWA, run offline, and install it!​

Hopefully, you're ready to try something fun that will reinforce what you learned today.

For this exercise:

• Fork the PWA on SWA Starter repository and deploy it to Azure Static Web Apps using the skills you gained in the previous chapters of the #30DaysOfSWA
• Open the url you received after the SWA resource was created
• Now, go offline (disconnect from the Internet or emulate offline mode in the DevTools) and reload the page - it still works!
• Using the "App available" icon on the right-hand side of the desktop browser's address bar, install the application on your laptop - now it behaves like a native one!

Resources​

Here are some resources to get you started with your Progressive Web App journey into

• PWA on Microsoft Docs
• #30DaysOfPWA
• Workbox library

We made it to the end of Week 2!! Let's give ourselves a round of applause!

In the last week we walked through a subset of usage examples featuring diverse applications, static site generators and front-end frameworks. And that's still just a small slice of what is possible. So how do you make this journey more actionable and learn by doing?

That's what I'll try to answer in today's post. Also bookmark this one because we will revisit it at the end of next week ("Dev Tools") and try to replicate some of these tutorials using the more streamlined experience provided by the Azure Static Web Apps CLI (a command-line tool for local development).

What We'll Cover​

• Recap: Usage Examples Week
• Build: How to Get Project Ideas
• Share: Contribute to the Gallery
• Simplify: Using Static Web Apps CLI!
• Exercise: Build, Deploy, and Customize, some starter app.x

Week 2 Recap​

This week was packed with different usage scenarios and front-end technologies. Let's take a quick look at what was covered:

• Monday: We built a personal blog using Astro.
• Tuesday: We built an inventory management app using React
• Wednesday: We got creative with Vue, ML and Game Engines!
• Thursday: We published content using Docusaurus
• Friday: We explore headless CMS examples using Blazor WebAssembly
• Saturday: We learned to make SWA a more progressive web app

The visual roadmap gives you a sense of what was covered each day. But this is just the tip of the iceberg. JavaScript developers have a wide variety of front-end frameworks and static site generators to work with. And, as we saw with Blazor WebAssembly, non-JavaScript developers have other frameworks they use to develop modern web applications. So, how can you continue the learn-by-doing journey? Read on for some ideas.

Project Ideas​

1. Static Sites​

The easiest way to get started is to use one of many static site generators available today. Most of these provide templates you can start with, and customize just by bringing your own content (data, media assets etc.). Need some inspiration? Take a look at the recently released Rising Stars Of JavaScript: Static Sites list and see if any of those projects have starters you can repurpose.

Example: My "Recipe Me" Project.

Earlier this week, we covered examples with Astro (#2), Docusarus (#3) and VuePress (#9) in our usage examples. Today we look at Eleventy (#7).

Earlier this year I ran #30DaysOfPWA, a similar series focused on Progressive Web Apps. And I wanted a demo! I've always wanted to have a recipe blog, and I found this Eleventy starter that was perfect. I customized it to add the features and code required to make it PWA-compliant. And I configured it for hosting on Azure Static Web Apps. Bonus: I learned a lot in the process about the framework, and the configuration changes for SWA!

Related Resources:

• Read the Tutorial
• Browse the Source
• Visit the Website

2. Frameworks​

The next step up from this is to look at existing application starter-kits or tutorials that target popular front-end and full-stack frameworks. Unlike static site generators (which are content-centric) these apps let you explore advanced user interactions that can benefit from SWA concepts like serverless API and authentication support. Need some inspiration? Take a look at the recently released Rising Stars Of JavaScript: Front-end Frameworks list and see if any of those projects have starters you can repurpose.

Example: Simona's "Sticker Shop" Project.

Check out this example from Simona Cotin (currently a Principal PM on the Static Web Apps team) which forked the Strapi e-commerce starter and adapted it for deployment on Azure Static Web Apps. The Strapi tutorial talks you through the setup and structure of the application - making it a perfect place to explore just adding SWA integrations. Bonus: Simona's deployment also takes advantage of SWA's custom domain support, making the app accessible at the https://aswa.cloud domain.

Related Resources:

• Read the Tutorial
• Browse the Source
• Visit the Website

3. OSS Apps​

Sometimes, you find the right application not because of the framework - but because its a use case that really resonates with you - even if you are not necessarily familiar with the underlying technology. These projects are great because your interest in the end result makes you more curious to dig under the hood, improving your understanding of new applicaton architectures and tooling. Need some inspiration? My favorite starting point is the awesome repo which is a directory of awesome-XYZ lists for a given technology XYZ. Many of these lists identify tutorials, open-source projects and starter template repos that can be the basis for your experiments!

Example: My "Google Codelabs" Project.

If you've attended any Google Developer events or community conferences, chances are you'll have encountered their Codelabs site - a repository of step-by-step tutorials that cover a wide range of technologies. But did you know that they open-sourced the codelabs management and hosting tools?

The underlying tooling uses Golang but the actual content is written in Markdown, and converted into the required static files by claat, the "Code Labs As A Tool" utility. Follow along to create your own codelabs - and host them on Azure Static Web Apps. Bonus: The hosted app is the tutorial for how it was created. Isn't that meta?

Related Resources:

• Read the Tutorial
• Browse the Source
• Visit the Website

Share: Gallery​

We've talked about Project ideas that help you learn by repurposing the open-source projects, tutorials or templates generated by others. Now let's talk about paying it forward by sharing your project to inspire others.

That is the purpose of the Static Web Apps Showcase that we will be debuting before the end of May. You can see a sneak preview of what the app gallery looks like, allowing developers to search for projects that have live deployments and open source codebases, and use one of the listed front-end technologies. Bookmark this post or track the Showcase link on this site, to know when the Showcase feature goes live! Be the first to submit a project for some of the more recent technologies added to that list!

Simplify: SWA CLI​

One last thing. In all the usage examples and tutorial so far, we've typically emphasized either the IDE option (using the Visual Studio Code SWA extension) or the Azure Portal option (activated by the Deploy to Azure button configured on repo README).

But what if you could do everything from the command-line - from initializing your project configuration, to building and testing your application locally, to deploying it to the cloud in a production or preview environment? That's the promise behind the Azure Static Web Apps CLI. Join us May 19 for a special #SWAanniversary event for some exciting announcements in this context.

Then bookmark and revisit this page later in May for an updated section where we discuss how we can further simplify and streamline our "learn by doing" projects with this tool!

Exercise​

We've looked at various resources you can start with, to scaffold a real-world application that you can then configure for SWA deployment and further customization. Go ahead and pick something and expand on the app to create something new. Then contribute it to our upcoming Showcase project!

Need more inspiration? I'm a fan of React, but I've wanted to explore Preact as a performant alternative with a comparable API. The Preact Demos page has a rich set of examples - including this Homepage Generator which is a perfect 1-page resume template you can customize for your profile. Try it out!

We just crossed the halfway mark on #30DaysOfSWA! We covered core concepts in Week 1, and explored usage examples in Week 2. Today we kick off week 3 with a focus on Developer Tools! Let's dive in!

What We'll Cover​

• What does the Developer Experience look like?
• Explore: Azure CLI
• Explore: Azure Portal
• Explore: Azure Core Functions Tools
• Exercise: Explore Azure Portal & CLI docs for SWA.

Dev Experience​

When we think about building a modern web application, we're also thinking about our developer experience. By one definition, developer experience refers to how easy or difficult it is for us, as developers, to perform the required tasks to implement the desired outcome.

In the case of application development, the tasks often involve:

• Building the project from source (after creating the codebase)
• Testing project behaviors (to validate compliance with requirements)
• Deploying the project (to staging or production environments)
• Debugging the project (to fix issues, audit performance etc.)

Having the right developer tools can make all the difference between a productive developer workflow and a painful one. This week, we'll look at the many tools and services available, that make the Azure Static Web Apps Developer Experience more seamless.

• Azure Dev Tools | What are the core tools for working with Azure?
• Playwright | How can we implement end-to-end testing for our app?
• CI/CD| How can we automate build/deploy workflows?
• Edge DevTools How can we debug and profile apps in the browser?
• SWA CLI How can we simplify local development for static web apps?
• Visual Studio Code How can we supercharge our IDE-driven experience?

In today's post we'll look at the main tools that make it easy for modern web application developers to build static web apps on Azure:

• Azure CLI - a command-line interface to create and manage Azure resources
• Azure Portal - a web-based unified console alternative to the Azure CLI.
• Azure SWA CLI - a local development tool for Azure Static Web Apps
• Azure Functions Core Tools - a local development tool for Azure Functions.
• Azure Extensions for Visual Studio Code for seamless access from IDE.

We'll coverAzure SWA CLI and VS Code extensions in greater detail later this week.

New to Azure?​

We assume you are familiar with cloud computing concepts like resources, resource groups, subscriptions and services. If not, that's okay. Now's a good time to take a detour and explore Azure Fundamentals - a 6-part learning series that will take you through the core concepts, services, solutions, security features, identity & governance aspects, and cost management features available on Azure.

If you're a JavaScript or Node.js developer new to Azure, bookmark these links:

• Azure SDKs for service integrations in your preferred programming language.
• Azure for JavaScript Developers for guides and samples
• Tools for JS Developers on Azure with configuration tips

Azure CLI​

Now that you're familiar with core Azure concepts, let's talk about how you can create and manage your cloud resources on Azure. The Azure CLI is a cross-platform command-line tool that connects you securely to Azure, to execute commands on Azure resources interactively (or via scripts) from a terminal.

The easiest way to familiarize yourself with the Azure CLI commands is to install and run it in Azure Cloud Shell in your browser - no local installation needed. Follow these instructions to then install it locally in your development environment. Validate your install by testing out the core az command.

az --version

There Azure CLI can manage most Azure Services out of the box. Here is list of supportred services along with links to quickstart documentation for each. As web developers, you may find the web-related subset of services worth exploring - everything from App Service and API Management, to Azure Static Web Apps.

Use the following command to get interactive help with supported commands and options in this context.

az staticwebapp --help

With the CLI you can manage app settings, create and delete static apps, manage the static app's environment and associated functions, oversee information related to identity, users and secrets associated with the app, and more.

• Explore the az staticwebapp reference to learn relevant commands and options.
• Then build your first static web app using the Azure CLI.

Azure Portal​

If you prefer a unified web-based console for managing your Azure resource interactions, the Azure Portal provides a graphical user interface alternative to the Azure CLI. The portal is designed for continuous availability. Here's a snapshot of what the Azure Portal layout looks like. Browse the following documents to get a deeper dive into its capabilities:

• Understand the components of the Azure Portal in this document.
• Then learn to navigate the portal in this tutorial.
• Or follow the Azure Quickstart Center guided tour.

Then, try to build your first static web app using the Azure Portal to get hands-on experience with the developer workflow from creation to deployment.

Functions Core Tools​

Azure Static Web Apps uses Azure Functions to support serverless API capability for the app. Learn more about this in our earlier post on API-enabling SWA where we talked about Managed Functions (created and managed by Azure Static Web Apps) and Bring Your Own Functions (independently created and managed) options for adding serverless API support to your static web application.

The Azure Functions Core Tools - aka func - supports local development with a command-line tool to create, test, and even deploy, your functions to Azure. Once installed, use the following to get interactive help with the supported commands and options for this tool:

func --help

You should see something like this (some output abbreviated for clarity) giving you a sense of the main operations you can perform from this CLI.

Azure Functions Core Tools
Core Tools Version:       4.0.3971 ...
Function Runtime Version: 4.0.1.16815

Usage: func [context] [context] <action> [-/--options]

Contexts:
azure       Commands to log in to Azure and manage resources
durable     Commands for working with Durable Functions
extensions  Commands for installing extensions
function    Commands for creating and running functions locally
host        Commands for running the Functions host locally
kubernetes  Commands for working with Kubernetes and Azure Functions
settings    Commands for managing environment settings for the local Functions host
templates   Commands for listing available function templates

Actions: 
start   Launches the functions runtime host  
    --port [-p]     Local port to listen on. 
                    Default: 7071
..
..

Explore the documentation to learn how you can:

• Install the Azure Functions Core Tools
• Create a local Functions project
• Run and test Functions locally
• Publish Functions to Azure

Later this week, we'll do a deep-dive into the Azure Static Web Apps CLI - a local development commandline tool for Azure Static Web Apps, that works seamlessly with the Azure Functions Core Tool, to deliver an unified developer experience for creating and testing your API-enabled Static Web Apps projects.

The combination of Azure CLI (to manage Azure resources from command line), Azure Functions Core Tools (to manage Azure Functions local development and deploy) and Azure Static Web Apps CLI (to manage SWA local development and deploy) provides a seamless command-line driven developer experience for web developers on Azure.

Azure Extensions​

But what if you prefer an IDE-based approach? Visual Studio Code has you covered. In a post Later this week, we'll look in depth at the key Visual Studio Code Extensions you can use, to supercharge your developer experience from code to cloud, right inside the IDE. For now, I'll leave you with these resources:

• Read the Azure Extensions documentation to learn how to find, and install, relevant extensions in VS Code.
• Explore the Deploying Applications To Azure page for hands-on tutorials for VS Code - including one for Azure Static Web Apps and one for Azure Functions
• Search the VS Code Marketplace for relevant extensions from both Microsoft and the broader developer community.

Here is a snapshot of extensions currently published by Microsoft in the Azure category, sorted by Trending metrics. You can see the Azure Static Web Apps Extension listed here -- we'll cover that in more detail in the final post of this week!

Exercise​

Wow - we covered a lot today!! But don't worry about having to remember all of it. The goal was to raise awareness of which tool to use, when, and why. Your exercise today:

• pick either Azure Portal or Azure CLI documentation for Azure Static Web Apps, and familiarize yourself with the many commands, settings and options available.

• Try the default quickstart for that option - then explore other commands with the deployed Static Web App to get a real sense of how this works.

Resources​

• Azure CLI documentation - with Static Web Apps Quickstart
• Azure Portal documentation - with Static Web Apps Quickstart
• Azure SWA CLI documentation
• Azure Functions Core Tools documentation
• Azure SDKs for JavaScript and other languages
• Azure Extensions for Visual Studio Code

Yesterday we kicked off "Developer Tools" week by talking about the end-to-end developer experience associated with building modern web applications. Today we focus on a key segment - testing. Let's look at what test automation means for modern web applications, and how Playwright can help you automate end-to-end testing of your Azure Static Web App.

What We'll Cover​

• Test Automation for Modern Web Apps
• What is Playwright?
• Get Started With Playwright
• Explore Playwright Tools
• Use Playwright with SWA
• Exercise: Try the Tutorial with your deployed app.

Test Automation​

Modern mobile web applications have to work correctly and consistently across all modern browsers (like Chromium, Firefox or WebKit) and the device platforms they run on (with varying screen sizes, orientations). Testing your application UI/UX manually becomes difficult when we think about the granularity of tests across these combinations. Testing manually becomes impossible when we factor in the frequency at which testing needs to be done to validate these on every code commit or pull request. This is where test automation shines!

Test Automation is about executing tests automatically to validate software specs, then using the reported insights to improve software quality iteratively. For web apps, this requires tools that can automate test actions in the browser (web automation) and support this consistently across browsers. This is where Playwright shines!

Playwright Overview​

Playwright is an open-source framework for reliable end-to-end testing of modern web apps. It features a built-in Playwright Test Runner for automating test execution, and supports a Playwright Library to simplify integration into third-party solutions.

This visual guide shows the key features of the framework (downloadable hi-res version here) with these useful features:

• Unified API - you write tests once, they run on all browsers and devices.
• Mobile Web Testing - rich set of device profiles, usable with native emulators.
• Multi-Language Support - write tests in Java, JS/TS, Python or C#.
• Reliable Testing - no flaky tests thanks to auto-waiting and web-first assertions
• Powerful Tooling - get help authoring, debugging, profiling, and reporting, tests.
• Full Isolation - browser contexts (in just ms), options to parallelize tests

Check out the Playwright documentation and API for more details.

What kinds of things can we test with Playwright?

• Test if UI component behaviors work as expected (events)
• Test if UI workflows are correct (navigation, inputs)
• Test UX behaviors in different contexts (with fixtures)
• Modify network traffic (auth, proxy etc.) for testing
• Validate behaviors under network conditions (modified)
• Validate behaviors for device contexts (emulated profiles)
• Automate capture of evidence (videos, screenshots) in tests

Explore the Guides and Demo.Playwright for usage examples. And check out Debbie's playwright-testing series for more examples of Playwright in action.

Playwright Quickstart​

It's time to get some hands-on experience with Playwright. Check out the Getting Started guide on their site for reference.

However, we'd like to walkthrough it with a real-world example in mind and figure out how to go from the boilerplate setup to the start of a basic script and configuration that sets us up to do more for testing our Azure Static App.

#30DaysOfSWA Website Example: Step-by-Step Tutorial:

Check out this repository that I setup today, to use the quickstart guide as a basis for setting up end-to-end testing for the #30DaysOfSWA website! The README documents the following steps in detail:

• Setup Testing Repo
• Install Playwright
• Explore Boilerplate (setup)
• Run Default Test
• View Generated Test Report
• Automate Tests with GitHub Actions
• View Actions-Generated Report Assets
• Customize Default Script/Config for My App
• The Joy Of Trace Logs!!
• You Did It!

By the end of this tutorial you should have:

• A starter test script customized for your application
• A test configuration file with tracing on to capture detailed profiling data
• A GitHub Actions workflow that automates test runs with each codebase change.

At this point, you are now ready to build on this:

• add more tests to your example.spec.js file => see: Playwright Test API
• configure your test run in playwright.config.js. => see:Configuration Object

Playwright Tooling​

In the tutorial above, we mentioned some Playwright tools (CLI, TraceViewer, HTML Reporter, Codegen) in passing. Playwright has a really powerful set of tools that can streamline your end-to-end testing experience from authoring to reporting.

Start by familiarizing yourself with the Playwright CLI.

It's the main launching pad for all other command-line utilities. Using the CLI you can navigate to pages ("open"), install browser dependencies ("install"), take screenshots ( "screenshot"), launch the test runner ("test"), author tests ("codegen"), view traces ("show-trace") and more.

Launch the CLI as follows:

npx playwright <command> [options]

Use npx playwright --help for details on commands and options supported in your installed CLI version. Want a deeper dive?

• Check out Nitya's Tool Talk Post for detailed coverage.
• Download this handy hi-res visual guide as a cheatsheet

Usage Example:

Let's use the screenshot command to capture an image of the kickoff post from the #30DaysOfSWA website for an "iPhone 6" device profile. You can see the named device profiles currently supported for reference.

npx playwright screenshot --device "iPhone 6" https://www.azurestaticwebapps.dev/blog/kickoff 30Days.png

Navigating to https://www.azurestaticwebapps.dev/blog/kickoff
Capturing screenshot into 30Days.png

Result: This is what the saved image looks like.

Then start exploring these tools:

• Inspector - a GUI-based tool for debugging test execution
• TraceViewer - a GUI-based tool to explore recorded test traces
• Codegen - an authoring tool to generate tests based on user interactions
• Debugging - additional tools to support runtime debugging
• Reporters - built-in reporters of different types

What's Next​

We covered a lot today.

At this point, you should know what Playwright its, and why it's useful for automating tests for modern web applications. You should have a sense of the powerful developer tools it has, and understand how to setup and configure it for use with your Azure Static Web App. And you should have a clean basis for building up your test suite.

So where can we go next to skill up? We have you covered:

• Watch this repository I setup today. I hope to continue adding more tests that can walk through various Playwright features with a deployed SWA,, and use that to explore both the Playwright capabilities and SWA-specific features or usage.

• Join us tomorrow when we explore a "Multi-Stage Deployment with Azure DevOps" demo that shows you a full-stack application with Playwright tests integrated. Learn interesting aspects - like using SWA environment variables to define test parameters - that highlight best practices for test setup in SWA.

• Last but not least, check out this talk from last year for more insights into End-to-End Testing for Playwright from the Azure Static Web Apps Team.

Exercise​

Pick one of the apps you've built (or use) - preferably one that is currently deployed to Azure Static Web Apps so you can explore other scenarios later.

Walk through the same steps with your deployed app - then try adding one new test script that goes beyond the starter test case. Look at the demo project for inspiration!

What We'll Cover​

• Build SWA with Azure Functions API + Playwright Tests
• Deploy SWA to staging environment
• Automate validation of staged app with Playwright
• Wait for manual approval
• Deploy to production
• Exercise. Explore the Demo Application Source and try it out!

Azure Static Web Apps recently introduced the ability to automatically configure an Azure DevOps pipeline to build and deploy your app. It's a great way to get your app up and running quickly.

For production applications, it's common to first deploy an app to staging environment(s) prior to deploying to production. In this article, we'll walk through how to configure a robust Azure DevOps pipeline that will:

• Build an app, Azure Functions API, and Playwright tests
• Deploy the app to a staging environment
• Automatically validate the staging app with the Playwright tests
• Wait for a manual approval
• Deploy your app to production

Sample application​

We'll use a .NET 6 full-stack application.

• Frontend: Blazor WebAssembly
• Backend: Azure Functions
• Tests: Playwright

To follow along, import the repository into your Azure DevOps project. You can use similar steps for a Node.js app.

Create a static web app and deployment pipeline​

Recently, Azure Static Web Apps added the ability to generate an Azure DevOps pipeline to deploy your app.

You can create a static web app and the deployment pipeline in a single step.

1. In the Azure portal, search for and create a new static web app.

2. During the creation process, select "Azure DevOps" as the deployment source and select the DevOps repository and branch that contains the app.

   

3. In the build presets, select "Blazor". The pre-populates the app and API folder locations.

   

When you create the app, a new pipeline YAML file will be created in the repository. It'll automatically run. It takes a few minutes to build and deploy the app.

Open the pipeline YAML file in your browser or locally in an editor to see its contents. It contains a single AzureStaticWebApp task that automatically builds and deploys the app.

Create Azure Pipelines environments​

Azure Pipelines allows you to define environments. Environments are useful for adding manual approvals to your pipeline.

We'll create two environments — Staging and Production. They'll correspond to the two Azure Static Web Apps environments we'll deploy to.

To create a Pipelines environment, select "Environments" under Pipelines.

Create one named "Staging". Because you don't need a manual approval for this stage, you don't to configure anything else.

Next, create a new environment named "Production". Because we want to require a manual approval before deploying to production, you can configure the environment to require a manual approval.

1. In the environment's "Approvals and checks", select "Approvals".

2. Add yourself as an approver and create the approval policy.

The pipeline you'll update later will reference these environments.

Protect Azure Static Web Apps environments with a password​

Azure Static Web Apps provides preview environments to let you test out your app before deploying to production.

Preview environments were intially available for pull requests in GitHub. Recently, Static Web Apps introduced the ability to arbitrary define named preview environments. For instance, we can create an environment named "Staging".

Preview environments are public by default. This is great for open source projects, but sometimes we want to protect them from public access.

You can add password protection to your app's preview environments.

1. In the Azure portal, open your static web app.

2. In "Configuration", select the "General settings" tab.

3. Select "Protect staging environments only" and enter a password.

   

You also have the option to protect all environments. But in this app, we want the production environment to be accessible to the public.

Configure the multi-stage pipeline​

Now that we've configured the Azure Pipelines environments and password protection, we can configure the pipeline.

Open the pipeline YAML file in your browser or locally in an editor. Replace its contents the contents of this file.

We'll walk through the different parts of the pipeline. It has 3 main stages: build, deploy to staging, and deploy to production.

Stage 1: build the app​

trigger:
- main

pool:
  vmImage: ubuntu-latest

stages:

- stage: Build

  jobs:
  - job: build
    displayName: Build app

    steps:
    
    - task: UseDotNet@2
      displayName: Install .NET SDK
      inputs:
        packageType: 'sdk'
        version: '6.0.x'
        
    - script: |    
        dotnet publish -c Release -o "$(Build.ArtifactStagingDirectory)/frontend"
      displayName: Build Blazor frontend
      workingDirectory: $(System.DefaultWorkingDirectory)/Client
      
    - script: |  
        dotnet publish -c Release -o "$(Build.ArtifactStagingDirectory)/api"
      displayName: Build Azure Functions API
      workingDirectory: $(System.DefaultWorkingDirectory)/Api
      
    - script: |
        dotnet build -c Release -o "$(Build.ArtifactStagingDirectory)/tests"
      displayName: Build Playwright tests
      workingDirectory: $(System.DefaultWorkingDirectory)/PlaywrightTests

    - task: PublishBuildArtifacts@1
      displayName: Publish artifacts
      inputs:
        PathtoPublish: '$(Build.ArtifactStagingDirectory)'
        ArtifactName: 'drop'
        publishLocation: 'Container'

The pipeline triggers on any changes to the main branch. If your app uses a different branch, you can change it.

The pipeline then builds the app, Azure Functions API, and Playwright tests. It then outputs the artifacts. The same build artifacts are deployed to all environments. This ensures that the app you tested in other environments is the same one you're deploying to production.

Stage 2: deploy to staging and run Playwright tests​

- stage: deploy_staging
  displayName: Deploy to staging

  jobs:
    - deployment: deploy
      displayName: Deploy and test
      environment: Staging
      variables:
      # Change the variable group name to match the one in the generated pipeline
      - group: Azure-Static-Web-Apps-calm-coast-0df39b910-variable-group
      strategy:
        runOnce:
          deploy:
            steps:

            - download: none
            - checkout: none

            - task: DownloadBuildArtifacts@1
              displayName: Download artifacts
              inputs:
                buildType: current
                downloadType: single
                artifactName: drop
                downloadPath: $(System.ArtifactsDirectory)

            - task: AzureStaticWebApp@0
              displayName: Deploy to staging environment
              inputs:
                app_location: frontend/wwwroot
                api_location: api
                skip_app_build: true
                skip_api_build: true
                verbose: true
                azure_static_web_apps_api_token: $(AZURE_STATIC_WEB_APPS_API_TOKEN_CALM_COAST_0DF39B910)
                deployment_environment: staging
                workingDirectory: $(System.ArtifactsDirectory)/drop

            - task: UseDotNet@2
              displayName: Install .NET SDK
              inputs:
                packageType: 'sdk'
                version: '6.0.x'

            - script: |
                chmod -R a+x $(System.ArtifactsDirectory)/drop/tests
                sudo --preserve-env=PLAYWRIGHT_BROWSERS_PATH pwsh $(System.ArtifactsDirectory)/drop/tests/playwright.ps1 install --with-deps chromium
                dotnet test $(System.ArtifactsDirectory)/drop/tests/PlaywrightTests.dll --logger trx
              displayName: Run Playwright tests on staging app
              env:
                PLAYWRIGHT_BROWSERS_PATH: $(Build.SourcesDirectory)/browsers
                LOGIN_PASSWORD: $(LOGIN_PASSWORD)
            
            - task: PublishTestResults@2
              condition: succeededOrFailed()
              inputs:
                testRunner: VSTest
                testResultsFiles: '**/*.trx'

This is the most complex stage. Note that it references the "Staging" environment we created in the Azure Pipeline. It also references the variable group that was automatically generated when the static web app was first created. Change its name to match the variable group in the generated pipeline.

This stage starts by downloading the artifacts from the build stage.

Next, it uses the AzureStaticWebApp task to deploy the app to the staging environment.

• skip_app_build and skip_api_build are set to true because the app and API artifacts were already built and don't need to be built again.
• deployment_environment is set to staging because we want to deploy to the staging environment.

After the app is deployed, the pipeline installs the .NET SDK and runs a script that installs the required dependencies for Playwright. Playwright is a testing framework that automates running tests in a browser.

After the dependencies are installed, the script runs the Playwright tests using the dotnet test command.

One thing to note is that we need to configure a secret variable named LOGIN_PASSWORD. This is the password that the user will enter when they log into the staging environment. The Playwright tests will use this password to log in when it runs tests on the staging environment.

The last step in the stage publishes the test results.

Stage 3: deploy to production​

- stage: deploy_production
  displayName: Deploy to production

  jobs:
  - deployment: deploy
    displayName: Deploy
    environment: Production
    variables:
    # Change the variable group name to match the one in the generated pipeline
    - group: Azure-Static-Web-Apps-calm-coast-0df39b910-variable-group
    strategy:
      runOnce:
        deploy:
          steps:
          - download: none
          - checkout: none

          - task: DownloadBuildArtifacts@1
            displayName: Download artifacts
            inputs:
              buildType: current
              downloadType: single
              artifactName: drop
              downloadPath: $(System.ArtifactsDirectory)

          - task: AzureStaticWebApp@0
            displayName: Deploy to production environment
            inputs:
              app_location: frontend/wwwroot
              api_location: api
              skip_app_build: true
              skip_api_build: true
              verbose: true
              azure_static_web_apps_api_token: $(AZURE_STATIC_WEB_APPS_API_TOKEN_CALM_COAST_0DF39B910)
              workingDirectory: $(System.ArtifactsDirectory)/drop

This stage references the "Production" environment in the Azure Pipeline. Because we configured this environment to require approval, this will trigger a manual approval step before this stage is run.

Like the previous stage, this stage downloads the artifacts and deploys them with the AzureStaticWebApp task. This time, no deployment_environment is set because we want to deploy to the production environment of the static web app.

Run the multi-stage pipeline​

Now that the pipeline is set up, you can run it by saving the file. If you edited it locally, don't forget to push it to your Azure DevOps repo.

After the "Deploy to staging" stage is run, you should see that the Playwright tests have been run to validate the staging environment and the results are published.

The pipeline run is paused because the "Deploy to production" stage requires an approval.

When you approve the pipeline, the pipeline will run again.

After approval, the app is deployed to production.

A closer look​

Before we end this article, we want to dive a bit deeper into the Static Web Apps environments and the Playwright tests.

Azure Static Web Apps environments​

To see the environments you've created, click your static web app's "Environments" tab in the Azure portal. You should see the production and staging environments.

Playwright tests​

The Playwright tests are located in the PlaywrightTests project and they're written in C#.

Playwright can be used to automate testing of web apps using real browsers. The tests in the example use Chrome (Chromium), but Playwright also supports Firefox, WebKit, and Microsoft Edge.

This is an example of a Playwright test in C#. It navigates the browser to the app's homepage, clicks on the "Fetch data" link, and confirms that the data is fetched from the backend API and it is rendered successfully.

[Test]
public async Task ShouldLoadWeather()
{
    await using var browser = await Playwright.Chromium.LaunchAsync();
    var page = await browser.NewPageAsync();
    await GoToHomePage(page);

    await page.ClickAsync("a[href='fetchdata']");

    var h1 = await page.QuerySelectorAsync("div#app main h1");
    var h1Text = h1 == null ? "" : await h1.TextContentAsync();
    Assert.AreEqual("Weather forecast", h1Text);

    var rowsSelector = "div#app main table tbody tr";
    // wait for table to have rows
    await page.WaitForFunctionAsync($"document.querySelectorAll('{rowsSelector}').length");
    var rows = await page.QuerySelectorAllAsync(rowsSelector);
    Assert.AreEqual(5, rows.Count);
}

The tests use the AZURESTATICWEBAPP_STATIC_WEB_APP_URL environment variable to determine the URL of the app to test. In an Azure Pipeline, this variable is set by the Azure Static Web Apps task after a successful deployment. Because the tests run in the pipeline after a deployment to the staging environment, the variable contains the URL of the staging Static Web Apps environment.

Another interesting aspect of the tests is the following code for navigating to the homepage:

private async Task GoToHomePage(IPage page)
{
    await page.GotoAsync($"{siteBaseUrl}/");
    var homePageLocatorTask = page.Locator("text=Hello, world!").WaitForAsync();
    var passwordPageLocatorTask = page.Locator("text=Password protected").WaitForAsync();
    var isPasswordPage = (await Task.WhenAny(homePageLocatorTask, passwordPageLocatorTask)) == passwordPageLocatorTask;

    if (isPasswordPage)
    {
        System.Console.WriteLine("Found password page, logging in...");
        var passwordInput = await page.QuerySelectorAsync("input[type=password]");
        if (passwordInput == null)
        {
            throw new Exception("Could not find password input");
        }
        await passwordInput.TypeAsync(sitePassword);
        await page.ClickAsync("button");
        await page.Locator("text=Hello, world!").WaitForAsync();
    }
}

This code automatically logs in to the staging environment if the browser session is unauthenticated. At run-time, the sitePassword variable is set to the value of the LOGIN_PASSWORD secret variable.

Summary​

With the addition of features like named preview environments and automatic pipeline generation, it's now possible to configure complex, robust pipelines for building and deploying to Azure Static Web Apps from Azure DevOps.

Exercise​

The demo uses a .NET 6 full-stack application with a Blazor WebAssembly frontend, an Azure Functions backend, and integrated Playwright tests.

• Explore the source code here.
• Import the repository into your Azure DevOps project and follow the tutorial.

Resources​

• Video: Multi-environment deployments with Azure DevOps & SWA
• Repo with source code for demo

As we'll learn in a post later this week (stay tuned!), using the Azure Static Web Apps extension for VS Code makes it quick to create and manage your Web Apps directly from VS Code. But what about the other aspects of your developer experience - like debugging your web app or profiling its performance in the browser?

As a web developer, it's important to minimize context switching.

The fewer tools you need to use to do your job, the better. This way you can stay focused on the tasks at hand more easily, without having to constantly deal with multiple tools and windows on your computer. You become more productive when the tools you rely on work better together.

What We'll Cover​

• Getting started with the Edge DevTools VS Code extension
• Seamless debugging experiences for your front-end app.
• Discovering some of the DevTools accessibility tools.
• Discovering some of the DevTools performance improvement tools.
• Exercise: Install the Edge DevTools VSCode Extension and try these features out!

Debug front-end code from VS Code​

After you've created your SWA and have started adding more functionality to it, there will come a time when debugging your front-end code may become useful. Maybe you've added some JavaScript front-end logic that needs debugging, or maybe you've added new CSS layout code that needs inspecting.

The DevTools built in to your favorite browser come in very handy at this point. But, having to switch between your source files in your editor and your browser window to do the debugging can quickly become frustrating. It's also prone to errors as there aren't great solutions to move the tweaks you do in DevTools back to your editor.

One tool that can help a lot here is the Microsoft Edge Developer Tools extension for VS Code. This extension gives you DevTools in VS Code directly.

With this extension, the Elements and Network are embedded directly within VS Code, your Console messages appear in the VS Code console, issues detected by the Edge Issues panel are highlighted in your source code directly, and you get a live preview of your web app's front-end right in VS Code!

Finally, as you tweak your CSS code from within the Styles panel, your changes are automatically applied to your source files, even if you use a CSS pre-processor.

Get started with Edge DevTools VS Code extension​

First let's install the extension, right from VS Code.

1. In VS Code, open the Extensions sidebar, and search for "Edge Tools".
2. The Microsoft Edge Tools for VS Code extension should be listed. Click the Install button and wait for the process to end.

Once installed, the extension appears as a new icon in the Activity bar which gives you access to useful features. Let's jump straight in and make use of the most useful feature: generating a launch.json configuration file for your project.

1. Click the Microsoft Edge Tools extension icon in the Activity bar.
2. Click Generate launch.json. A file appears in VS Code with some useful configuration details we can tweak.

The most important configuration you should change now is the url and perhaps add a preLaunchTask if you need to.

I'll use my blog to illustrate the changes here. In this project, I have a build task configured that generates the HTML code for my blog from markdown, watches for changes in files, and serves the resulting site from HTTP port 8080.

So, in my case, I'll update the Launch Microsoft Edge in headless mode configuration in launch.json to this:

{
  "type": "pwa-msedge",
  "name": "Launch Microsoft Edge in headless mode",
  "request": "launch",
  "runtimeArgs": [
    "--headless",
    "--remote-debugging-port=9222"
  ],
  "preLaunchTask": "npm: serve",
  "url": "http://localhost:8080",
  "presentation": {
    "hidden": true
  }
}

When this launch configuration is used, it will build my blog from source code, serve it on a local server, open the browser directly within VS Code, and the DevTools panels alongside it. Let's test it! Click on Launch Project in the Microsoft Edge Tools extension to get everything running.

Now try to apply this to your own project, changing the configuration to match your needs. Next, we'll review the most useful features of the extension.

Mirror CSS changes to source files​

Tweaking CSS properties in DevTools is great because you get a live preview of your changes on the web page, and with the Microsoft Edge Tools extension, you also get mirroring of your changes right back to the corresponding source file. This way, you don't need to remember all of the changes you made and manually apply them to your editor. The extension is able to figure out the mapping between the live CSS code and the source files in your project.

Changing CSS code in the Styles panel automatically opens the corresponding source file and applies the same change.

Note that the extension does not save the CSS source file for you. You can keep on tweaking CSS in DevTools and, only once you're ready, save the changes made by the extension in the source file on your behalf.

You can learn more about CSS mirroring in the Microsoft Edge DevTools extension docs.

Find issues with your code​

Edge DevTools comes with a built-in Issues tool that provides useful information about the inspected web page. For example, it can report on browser compatibility, accessibility, or security issues.

The Microsoft Edge Tools extension in VS Code provides the same feature, but integrated right into your source code. For example, browser compatibility warnings are highlighted in your CSS source code with squiggly lines, and hovering over the highlight reveals more information about the issue.

You can also review all issues at once by opening the Problems panel in VS Code's bottom drawer.

You can learn about other ways to find issues with your code in the Microsoft Edge DevTools extension docs.

Get your console messages​

The Microsoft Edge Tools extension in VS Code also integrates the very popular Console tool. People rely on the console all the time when debugging their code.

Because the extension also works with the built-in VS Code JavaScript debugger, that means you can debug your front-end JavaScript code in VS Code as normal, and see your console logs in DevTools right next to you.

Learn about other DevTools features​

As we've just seen, the Microsoft Edge Tools extension is very helpful. It caters for most web development tooling needs, while ensuring you have a seamless experience without having to leave VS Code.

But there's more to the Edge DevTools available in the browser (the tools you get when you press F12) that's not yet available within the VS Code extension version.

Building a great SWA means building a great web app first and foremost and while learning the ins and outs of SWA is very important, learning about how to build a performant and accessible web experience for all your users is also crucial.

Let's discover a few tools and features of DevTools that can help you with this.

Fix accessibility issues​

Every year the WebAIM organization publishes a report of the most common website issues that create accessibility problems for people. Sadly, every year the result is quite depressing. You can read the WebAIM Million 2022 report.

On the bright side though, the most common accessibility issues can be detected and solved easily with DevTools! So let's learn about some of the features that can help create more accessible web experiences for all.

The most common accessibility problem out there is low contrast text. If the contrast ratio between the text color and the color of the background behind it is too low, then people might not be able to read the text at all. The color picker in DevTools is a great way to detect these problems.

1. Right-click a piece of text on your web page and select Inspect.
2. In the Styles tab, find the color CSS property that defines which color the text is, and click the colored square next to it.
3. Review the Contrast ratio in the color picker. Your goal is to have 2 check marks next to it, meaning that the contrast ratio meets the recommendation.

If the text doesn't have enough contrast, then you can fix the problem right here in DevTools.

1. Click the show more arrow next to the Color contrast value to reveal more information. Two lines will appear in the color picker.
2. Use these lines to choose a color that meets the recommendation.

Another very common accessibility problem is missing alternative text for images (or alt text). Alt text helps users of screen readers perceive the content of an image, but it also important for cases where users decide to disable images, or when images fail to load, and even for search engine optimization. And, DevTools can detect missing alt text automatically! So there's really no excuses for not writing great textual substitute for your images.

1. Open DevTools by pressing F12.
2. Click More Tools (+) in the main toolbar at the top and select the Issues tool from the list.
3. Check if the list of issues contains an Accessibility category. If it does, check for Images must have alternate text warnings.
4. Open one of the warnings, review the problem, and click Open in Elements to see the problem directly in the Elements tool.

Now let's talk about source order. The order in which assistive technology (such as screen readers) navigates a page is linked to the order in which the various elements appear in the document source code. Now, this order might be very different from the order in which the elements appear, visually, on the screen. Using CSS, you can re-order things visually, without changing the document source order.

So, to make sure the document navigation makes sense to all, even to users of assistive technology, it is important to check that the source order itself makes sense.

Edge and Chrome DevTools have a Source Order Viewer feature that helps with this.

1. Open DevTools by pressing F12.
2. Open the Elements tool and select a layout element which you want to check the source order in.
3. Click Accessibility in the tool's sidebar.
4. At the bottom of the Accessibility pane, select the Show source order checkbox. An overlay appears showing the source order with numbers.
5. Keep selecting different elements in the DOM tree to review their source order.

Improve performance​

Great performance can have a very positive impact on your website. A page that appears fast and responds to user actions instantly can impact user retention, engagement, and even revenue.

Performance improvement work can be daunting, but there are two useful tools in DevTools that can ease the pain: the Performance tool and the Detached Elements tool.

Let's start with the Performance tool. You'll find one in all browser DevTools, Edge, Chrome, Firefox, or Safari. They're all a little bit different, but at their core give you ways to understand the runtime performance of the inspected web page over a given period of time.

To use the tool in Edge:

1. Open DevTools by pressing F12.
2. Click Performance in the main toolbar at the top (you might have to click on the More tabs (>>) button first if the tab isn't visible.
3. Click the Record button.
4. Use the web page as a normal user would.
5. Stop the recording with the Stop button.

The Performance tool can tell you how busy (or idle) the browser was with things like running JavaScript code, reacting to user events, and re-rendering the page during the recording period. So it's a great way to find bottlenecks in your site's performance and therefore know what fixes would give the best bang for your bucks.

One example, if your site does a lot of animations and other visual things, is that the tool can report on frames per second (FPS) and alert you when the rate drops too low and could impact the user experience.

The Performance tool has a lot of functionality packed into a small user interface, so it can be important to go through its documentation to understand what everything does. To learn more, check out Get started analyzing runtime performance

Another important performance aspect is memory. How much memory your site uses of what's available, and whether it keeps on using more and more memory over time can make your site, and even the entire computer, run slow.

One type of memory leaks is DOM leaks, where the front-end JavaScript code does a lot of DOM node manipulation and, in the process, keeps references to more and more DOM nodes it doesn't need any longer. As the complexity of your app or site grows, it gets easier to make mistakes and introduce these types of memory leaks by accident.

Edge comes with a tool called Detached Elements which is great for investigating this type of memory leaks. Knowing that you have a leak isn't too hard, but knowing where it originates from can feel like playing hide-and-seek in the dark. The Detached Elements tool points at DOM nodes that are still around in memory but not used in the page, and tells you which part of your code still references them. This way you can take a look at your code, and decide whether these nodes are, indeed, being leaked and need to be destroyed, potentially saving a lot of memory and improving performance.

To use the tool in Edge:

1. Open DevTools by pressing F12.
2. Click More Tools (+) in the main toolbar at the top and select the Detached Elements tool from the list.
3. Click the Get detached elements button to list the DOM nodes in memory that aren't used in the page.
4. You can then use the app as a user would, and keep clicking that button to update the list. You can also click the Collect garbage button to force the browser to run its garbage collection mechanism, to see if some nodes have been collected in the meantime.

This should already give you a pretty good idea of where to start looking, but the tool is also integrated with the Memory tool, and using the Memory tool is great for finding where the listed DOM nodes are references from.

1. Click the Analyze button and wait for the heap snapshot to be taken.
2. Click any of the numbers appearing in the Id column to jump right from a DOM node in the Detached Elements tool to its list of retainers in the Memory tool.

The information displayed in the Retainers section of the Memory tool will give you hints as to which part of your code is currently keeping the DOM node alive in memory.

Learn more about using the Detached Elements tool in Debug DOM memory leaks with the Detached Elements tool.

Conclusion​

I hope what we saw today was useful. If there's one thing I'd love for you to take away from this is that building a great Azure Static Web App starts with building a great web experience for all!

Learning the tools at your disposal to find and fix the most common mistakes that prevent such a great experience is important, and the Edge DevTools VS Code extension eases the pain by integrating directly in your existing environment.

Exercise​

Install the latest version of the Microsoft Edge Developer Tools extension for VS Code and try out some of these features. Try identifying and fixing accessibility issues, or use the Performance tool to analyze the runtime performance, of a Static Web App you've deployed.

We're past the halfway mark in "Dev Tools" week! We looked at developer tools to help provision Azure resources, automate cross-browser testing, streamline CI/CD, and debug/audit your SWA for performance and accessibility. But what about local development - something to help me go from start (project creation & configuration) to finish (build & deploy) in one tool? Let's say hello to the Azure Static Web Apps CLI.

You may have missed it, but the new Azure Static Web Apps CLI is now available!

It would take a whole post to describe all the changes and new features, but here are some of the highlights. With the new init, build, start and deploy commands, the complete developement cycle of your app is now available in a single tool, directly from the command line.

To get started, make sur you have a recent Node.js version installed (>14) and type this command in your terminal:

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

We'll now have a look at the new commands and the most important features.

swa​

As the new CLI introduces a gazillion new options, it must quite a steep learning curve to get started? Quite the opposite!

Every command starts with swa, and now it might also be the only thing you'll need.

# yes, that's all you need to type
swa

This command is a macro shorcut for swa init, swa build, swa login and swa deploy. We'll get to the details of all these commands in a bit, the most important thing here is that swa is the only command you need to know to configure a new project for use with Static Web Apps, build it and deploy it. You don't have to worry about any options or flags, just type swa and you'll be on your way.

Creating the configuration​

The first of the new commands is swa init. This commands with detect your project configuration and the frameworks you're using to suggest a configuration for you, so you won't have to read through the shiny new docs to figure out what options you need.

After asking a name for your project configuration, you can validate or edit the detected project settings. Once finished, it will create a swa-cli.config.json file in the current folder with your settings. You can commit this file in your project repository so everyone from your team can use it.

Building your project​

After the configuration is created, you're all set to use other commands without having to bother with any options or flags.

Whether you need to build your front-end app, your API, or both, the swa build command will do the job. It also takes care of installing your NPM dependencies (if needed) detecting if you're using npm, Yarn or PNPM with your project.

Running your app locally​

Historically, being able to run your app locally was the first feature of the SWA CLI. Of course it's still there, and swa start allows you to emulate the SWA runtime environment, along with the routing, authentication features and API. A few changes were made to improve the developer experience, and of course bugs were fixed to more closely match the real SWA runtime.

Previously, if you were using an API, you had to install Functions Core Tools and make sure to match the tools version with the Node.js version you're using, but now the whole process is automated for you. If you don't have the tools installed or if the wrong version is installed, you don't have to worry about it: it will be automatically installed for you when needed.

Next steps​

With these new commands, you can already setup your project, build it and test it locally. Using swa start is also great for debugging your app and API in a live running environment. Once you're happy with the result, you can deploy it to Azure, and that's what we'll explore in the next post.

In the meantime, you can also head to the new docs website to learn more about the new features and how to use them.

Tell us your feedback!​

We're also here on dev.to to listen and help as much as we can! 🙂

Please tell us your experience, your difficulties, your questions, and what features you would like to see in the next versions of the SWA CLI.

Resources​

Want to see the Static Web Apps CLI in action? The tool became generally available yesterday, launching at the Azure Static Web Apps Anniversary. Watch the segment to see the SWA CLI in action.

This is second part of the 2-part series that focuses on the launch of the Azure Static Web Apps CLI at the Azure Static Web Apps Anniversary event on May 19, 2022. Yesterday's post introduced the core swa command and walked through the swa init and swa start commands - and covered configuration.

Today, we'll explore the swa login and swa deploy commands that help with deploying your locally-developed app to the Azure cloud. And we'll cover the use of Environment Variables to streamline the developer experience further.

For this second article about the SWA CLI, we'll talk about the new deployment options. And yes, you can now deploy your apps straight from the command line! Who's better than the person who implemented it to talk about it? I'll let my friend Wassim explain it all to you.

If you've never heard of Static Web Apps (or SWA for short), it's a web app hosting service provided by Azure, offering streamlined full-stack development with many built-in features like authentication, customizable routing, serverless functions and more. It also has a great free tier 😉

Logging in to Azure​

In the new SWA CLI for Azure Static Web Apps, we introduced a new swa login command allowing you to log in to your Azure account, straight from the command line. This command will encrypt and store your credentials in your system's key Chain, so you don't have to enter them again.

In most common cases, the swa login will pick your current active Azure credentials from the following locations (in this order):

1. Your environment variables, if you have set one or all of following variables:
   • AZURE_TENANT_ID
   • AZURE_CLIENT_ID
   • AZURE_CLIENT_SECRET
2. Your current Visual Studio Code, if you're using VS Code and is connected to Azure.
3. Interactive prompt using your browser.
4. The last fallback is the device code flow, which will prompt you to log in to your Azure account using a generated device code.

However, if you need, you can also provide any of these credentials from the command line, using the available flags:

Usage: swa login [options]

login into Azure

Options:
  -S, --subscription-id <subscriptionId>    Azure subscription ID used by this project
                                            (default: "process.env.AZURE_SUBSCRIPTION_ID")
  -R, --resource-group <resourceGroupName>  Azure resource group used by this project
  -T, --tenant-id <tenantId>                Azure tenant ID (default: "process.env.AZURE_TENANT_ID")
  -C, --client-id <clientId>                Azure client ID
  -CS, --client-secret <clientSecret>       Azure client secret
  -n, --app-name <appName>                  Azure Static Web App application name
  -cc, --clear-credentials                  clear persisted credentials before login (default: false)
  -u, --use-keychain                        enable using the operating system native keychain
                                            for persistent credentials (default: true)
  -nu, --no-use-keychain                    disable using the operating system native keychain

Once logged in, the SWA CLI will store your active Azure subscription ID and tenant ID in a local file called .env at the root of your project:

➜ swa login

Welcome to Azure Static Web Apps CLI (1.0.0)

Checking Azure session...
✔ Successfully logged into Azure!
✔ Saved project credentials in .env file.
✔ Successfully setup project!

This file will be used when deploying your project to Azure using the swa deploy command.

Deploying your app​

The new SWA CLI makes it even more easier to deploy your apps to Azure. You can now deploy your app directly from the command line, using one single swa deploy command.

The swa deploy command is smarter enough to figure out if you already have an Azure Static Web Apps instance available, and if so, it will use it. Otherwise, it will create a new one on the fly - or prompt you to select one from a list of already available ones:

➜ swa deploy

Welcome to Azure Static Web Apps CLI (1.0.0)

Using configuration "thundr" from file:
  /home/wassimchegham/oss/@thundr-dev/thundr/swa-cli.config.json

Deploying front-end files from folder:
  /home/wassimchegham/oss/@thundr-dev/thundr/app/dist/thundr-ui

Deploying API from folder:
  /home/wassimchegham/oss/@thundr-dev/thundr/api

Checking Azure session...
✔ Successfully logged into Azure!

Checking project settings...
? Choose your Static Web App › - Use arrow-keys. Return to submit.
❯   >> Create a new application
    swa_samples/angular-web-bluetooth
    swa_samples/catsify
    swa_samples/hexa
    swa_samples/ngxtools
    swa_samples/nitrooo
  ↓ swa_samples/photobooth-teams

The swa deploy command is also able to detect if your existing Static Web Apps instance has already been deployed from a CI/CD pipeline and inform you about it!

Deploying from a CI/CD pipeline​

Deploying from CI/CD pipelines is a common practice in many projects. You can use the swa deploy command to deploy your app to Azure from your CI/CD pipeline. You can accomplish this by setting a deployment token:

➜ swa deploy --print-token --app-name thundr --resource-group swa_samples

Welcome to Azure Static Web Apps CLI (1.0.0)

Checking project "thundr" settings...
✔ Successfully setup project!

Deploying to environment: preview

Deployment token:
7c3fc44b858164b677-truncated-8c80ace9-39a8-416c-ae22-864745c0470b003

swa deploy --deployment-token=7c3fc44b858164b677-truncated-8c80ace9-39a8-416c-ae22-864745c0470b003b003

You can also set the deployment token as an environment variable:

export SWA_CLI_DEPLOYMENT_TOKEN=7c3fc44b858164b677-truncated-8c80ace9-39a8-416c-ae22-864745c0470b003b003
swa deploy

Environment variables​

The new SWA CLI introduced a new set of environment variables to make it easier for you to configure your experience. You can customize the behavior of the SWA CLI by setting the following environment variables:

• General settings
• Emulator settings
• Deploy settings
• Runtime settings
• Login experience

You can read more about these environment variables in the Environment Variables section in our new documentation website.

Next steps​

From the start of your project to its deployment to Azure, with all the needed local testing in-between, you should now be equipped to take care of your complete development process all from the command line. Now the main challenge remaining for you is to deploy and grow your app 😉.

If you'd like to learn some tips you can use when developing your app, you can check out the Static Web Apps - Tips & Tricks video series.

You can also learn more about all the new features of the SWA CLI and how to use them by looking at the new docs website.

Tell us your feedback!​

We're also here on dev.to to listen and help as much as we can! 🙂

Please tell us your experience, your difficulties, your questions, and what features you would like to see in the next versions of the SWA CLI.

Resources​

Want to see the Static Web Apps CLI in action? The tool became generally available yesterday, launching at the Azure Static Web Apps Anniversary. Watch the segment to see the SWA CLI in action.

This week has been all about the SWA developer tools. To conclude the week, we'll show how the Azure Static Web Apps extension for VS Code can make using all of these awesome tools easier!

Prerequisites 🛠️​

1. Google Chrome installed - we make use of the debugger

2. Azure Static Web Apps extension for VS Code - View on Marketplace

3. Azure Static Web Apps CLI - View on GitHub

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

1. Getting started 🟢​

1. Clone one of these repositories, and open it up in VS Code

2. Run npm install

Theme: Cobalt2 Theme Official by Wes Bos

2. Run and debug 🐞​

1. Go to the "Run and Debug" view
2. Click "Show all automatic debug configurations."
3. In the dropdown, select "Azure Static Web Apps..."
4. Select the app you want to debug

This will start the Azure Static Web Apps CLI in the VS Code terminal, and launch the Chrome debugger on http://localhost:4280.

Now you can set and hit breakpoints in your frontend code.

3. Add API route ⚡️​

Azure Static Web Apps has integrated API support provided by Azure Functions. In order to add and debug an API route, we must install some Azure Functions tools.

1. Azure Functions extension for VS Code - Install from Marketplace

2. Azure Functions Core Tools - View on GitHub

npm i -g azure-functions-core-tools@4 --unsafe-perm true

Now, you can add an API route to your app using the command palette (press F1) and searching "Create HTTP Function".

Select a language (I chose JavaScript), then name your Function (I put "hello"). And then an API route will be created for you that you can make requests to at /api/hello.

4. Debug app & API ✨​

We can debug our API routes and our frontend app simultaneously in VS Code.

Select the "SWA: Run ..." debug configuration and click the green "Run and debug" button.

VS Code will now run your Functions API routes and your frontend. When it's all started, a Chrome window will open at http://localhost:4280.

Set a breakpoint in your Function endpoint.

Go to http://localhost:4280/api/hello in the Chrome window to hit the breakpoint.

5. Next steps 🏃‍♀️​

Now that you got your static web app running locally, you can deploy your static web app to Azure for free.

Troubleshooting 🔍​

If you're having issues, please check out the troubleshooting section in our wiki.

Resources 🔗​

• Azure Static Web Apps documentation
• Azure Static Web Apps CLI
• Azure Static Web Apps extension for VS Code

Next Week​

This marks the end of Week 3 of #30DaysOfSWA, with a focus on Developer Tools. Want a visual recap of what we covered .. here you go!! To recap:

• We provisioned Azure resources - using the Azure Portal and Azure CLI
• We added automated, cross-browser, e2e testing - using Playwright
• We built multi-stage deployment pipelines - using Azure DevOps
• We debugged and audited perf & accessibility - using Edge DevTools on VSCode
• We got unified local development and cloud deployment - using SWA CLI
• We explored rich extensions and seamless CLI interactions - using VS Code

So what do we have planned for next week?

We've already covered core concepts, usage examples and developer tools -- so that leaves: Best Practices! Join us for the final week of #30DaysOfSWA where we define the end-to-end developer experience, explore various Azure Service integrations to enhance your SWA, dive into a cool case study, and end with a Tips & Tricks series that brings you back full circle to development.

Thanks for sticking with us on this journey!

This kickstarts our "Best Practices" week where we'll explore additional topics that help up deliver an enhanced or more optimal modern web application experience to our users. We'll start by looking at the End-to-End developer experience (DX) - the importance of having a smooth and seamless DX to complement the UX (user experience), and best practices to improve your developer experience by architecting your applications and integrating services in more effective ways. Let's dive in!

Today we explore the importance of a great development experience and how can you improve yours, when building and deploying your static web applications using Azure Static Web Apps!

I admit it took me some time to write this post. It would have been much easier for me to write about a specific topic with code examples and technical definitions, than describing what developer experience means to me.

The definition of developer experience, like anything else you experience, is subjective. It has a lot of you, in it. It changes with you, and the context you're a part of. Things like how long you've been in the business or what type of software you work on, or where do you deploy it, will all impact your perception of an experience.

So how to put it in words? How to define it and scope it?

It's impossible for me to do it in a way that feels relatable to everyone. I can only explain it, from the perspective inferred by my needs and my perception of the outcome, as an individual developer, and how it impacts my vision and my work.

Predictability​

Let me start by saying that in my personal life, when I think of memorable experiences, a lot of them have been the consequence of an impulse. A spontaneous act. In my personal life, I am not much of a planner. I am the kind of person that wakes up every Saturday morning and declares "We are going somewhere far away this weekend!". And my husband (who is all the contrary from me and needs a lot of structure!) will ask questions like:

• Ok, where do you wanna go?
• Have you booked a hotel?
• Do you know where we will have lunch?

And I would invariably respond: "I don't care! Let's just hop in the car, drive somewhere and figure it all out on the way there!". That's because I think that experimenting and experiencing, go hand in hand, when it comes to adventure. And the actual way there, is part of the fun.

At work, however, I like predictability.

I like structure, repeatability, patterns & conventions. I appreciate having a framework, an opinion others agree with so I'm on the same page with my team. And I like all this because it oftentimes leads to quick results and success.

A Road Analogy​

Experiences are like roads. They can take you places -- or not. And to me, development experiences are just like the roads we travel on:

• They have milestones - so I can measure progress.
• They have multiple lanes - so I have flexibility.
• They have entry and exit ramps - so I can change paths quickly.
• They have destinations - so I know I'm getting somwhere specific.

When I first got into web development, there were a fewer types of roads. Most were linear and slow, particularly when it came to frontend development. You needed repeated round-trips to the same server, just to get something to render on a page.

By contrast, today we're speeding along multi-lane freeways with numerous twists and turns, interconnecting roads, and possibilities (aka configurations) to choose from. To reach a destination, you may have to use ramps to connect two different roads - similar to how we connect tow different services via an API.

If we continue with this analogy, then a bad development experience is like poor road planning or construction:

• the road is old, bumpy, cracked
• the signposts are few and far between, giving the user insufficient time to process and follow instructions.
• if you miss an exit, you may have to travel a long distance before you have the opportunity to turn around
• there may be no way to access a desired road from another one - no exit or entry ramps at all!
• if your car breaks down, or your run out of fuel - there may not be service stations nearby to for refill or recharge.
• or you may find a station, but you have no idea of the cost of refill or recharge before you commit to taking that exit.
• there may not be any way to get food or drinks for many miles.

You can probably guess how these travel constraints map onto poor developer experiences, but let's spell it out:

• having to slow down due to infrastructure conditions
• feeling like you're not making any progress
• having the certainty that your application quality is degrading due the environment and lack of resources or support, resulting in technical debt
• not having the ability to secure your implementation
• not finding the right, complete or fresh documentation to help you understand the best path
• not having the right SDK's, API methods, or means of integrating your app to other software, to accomplish simple or more complex tasks, like authentication, storage, content authoring with a headless CMS or setting up your CI/CD pipeline
• not having the right tools to build, deploy, optimize, preview, monitor or speed up your processes
• not being able to scale or not being sure how much it will cost you
• not having fun, as you go

Because, let's face it: developing should be a fun experience. And for that you need the right vehicle, the right infrastructure, and a plan. And when you lack all that, it's like riding a Lamborghini across a sandy desert.

Making the right architecture and technology decisions, will definitely impact the outcome. And we can only make those decisions right, when we ask the right questions.

Architecture: What core infrastructure, capabilities and resources do we need?​

As we hope you have learned from following this 30 days of Static Web Apps, it is a dedicated offering for frontend developers working with SPA's and Static Generated websites. We continue to work to extend its capabilities, and support more frameworks and use cases.

Documentation: Should be fresh & relevant!​

When thinking about those milestones that should hit along the road of a great end-to-end developer experience, we are working hard to make sure you always find complete and fresh documentation to help you get started and know all the possibilities you have with Static Web Apps, upfront, and to keep supporting you with relevant documentation and content as your applications grow.

Workflows: Building blocks & seamless integrations!​

Not only have we been working to offer an intuitive user interface at the Azure portal itself. We have been very intentional at the time of making sure integration with the tools, and platforms frontend developers know, use and love, like GitHub and VS Code, is seamless.

Static Web Apps automatically pushes a GitHub actions workflow file as you generate the application as a resource, and you can create it from the portal, if you prefer a UI guided experience, but also without ever leaving your favorite code editor, by installing the official extension!

And if you prefer a command line experience, you can use the brand new Static Web Apps CLI, with extended support to login to Azure, create, build and deploy apps, and a local emulator, so you can test your apps before you ever deploy to the cloud.

Creating your static web applications and configuring your pipelines, has never been this easy!

Efficient & Versatile: Serverless + Containerized APIs​

Because we recognize that the use cases for Jamstack and JavaScript full-stacks applications in general are becoming more and more complex, part of our strategy for a delightful end-to-end development experience relies on the simplification and standarization of mechanisms for API integration, via serverless functions through industry compliant patterns and via our super efficient devkits.

And that includes a concern that has historically been a challenge for frontend developers: the integration with databases and data storage. Azure Static Web Apps is unique in that it integrates very well with our CosmosDB database, a versatile cloud database that offers different API's to meet different developer skills and server a myriad of use cases in a very effective way.

Security & Performance: E2E testing + debugging​

And when we go to the service station, it may be a good time to check our oil levels, air pressure and wipe our window panes. And what a better way to do it than with tools from the same developer ecosystem and that play right (yes, you got me! I'm playing with words now!) like Playwright and Edge Developer Tools.

So now when you use the newly release Preview environments, to test development from a specific staging branch, you will have also the ability to integrate with best-in-class tooling, iteration after iteration, until feature complete.

Alignment: The ultimate e2e roadmap should map to the development cycle​

Any aspect on its own, can describe an end-to-end experience. For instance:

• If I want to secure my app against unauthorized access, I must implement identity. That's an E2E experience.
• If I want to persist data, I'll need to integrate with a database. An E2E experience.
• If I want to integrate third-party services on demand, I'll need event-driven functions. Another E2E experience.

The ultimate end-to-end experience, however, is that that encompasses all components described by a matrix of architecture definitions and best practices, mapping to the software development cycle itself.

When we are in the system design phase for our application, we will start thinking about what in research is known as "Jobs to be Done", and materialize them or get them done , using tools or integrating with other products or services.

Setup phase. Job to be done will be generic - "I need to build a static web app.

• What do I need? => I need a framework.
• What does the framework require => It's a JS framework that runs in the browser, or in a Node.js runtime. I need a node environment and a node package manager to manage dependencies.
• Selected framework has its own CLI => I need it to optimize it and build it.
• I want to version it, so I need a version control tool. To collaborate, I need to host that code in a central, remote location (aka version control hosting).
• And because we want to build it remotely each time we integrate with a CI/CD pipeline, that includes a runner and some virtualization or emulation. - And we want to publish it, so I need a hosting service.
• And..."_

And those are the requirements that we start mapping to setup and service capabilities, so we can put together local and remote environments capable to fulfill them.

Welcome to the matrix​

So let's do together an exercise of architecture definitions based out of developer jobs to be done, classifying them by the milestone we defined in the previous graphic. As a bonus, we will map them to a requirement, that can be a business requirement, a developer job to be done, or an end user story.

The matrix will be roughly based on the high-level diagram below:

(*)Expresses the ability to operate directly from the VS Code context via an extension, or locally with the CLI capability (†) Expresses the existence of an SDK to accelerate and secure the implementation

As we can see, you don't need to be part of a massive organization or a large, distributed team, to implement certain workflows and give structure to your own development cycles in process, to gain in developer productivity and delightful experiences.

Writing down your own matrix as you start, and extending it as your application scales and has extended requirements, can help you better organize yourself, make sure you're implementing best practices, and even evaluate tools and technologies to make sure you're on the right, most optimal path.

Static Web Apps is a modern, low configuration capability for Jamstack development, that offers you a myriad of satellite integrations, for free! And it has the advantage of growing with you, should you need more capacity, more tools, or even a full migration.

To wrap this up...​

Developer Experience is an end-to-end exercise that can be connected to the development, implementation and/or integration of a single feature or a group of them, from design, to execution, to testing, to release.

In order for developers to have a great experience they enjoy, from one end to the other, they need to find:

• guidelines that help them define a problem they can design an effective solution
• technologies that are compatible as building blocks for it
• complete, accurate and fresh documentation to support at all times
• tools that simplify the jobs to be done or tasks, individual and collective (to a single developer or a team of them)
• underlying mechanisms (exposed to the developer or not depending on their wishes or needs), for effectual program compilation, transpilation, testing, deployment and execution (such as runtimes and pipelines)
• definitions and hooks for integration (with other technologies) or and migration (to other technologies)

When all those, and some more, are fulfilled, developers become more productive, focused, and can spend their time doing what they love, instead of wasting it in undifferentiated tasks.

Exercise​

Try to reproduce the architecture seen above! Most of the integrations are available to the free tier! Show us how far you got!

Yesterday, we kicked off "Best Practices" week by talking about the end-to-end developer experience. Key to this is the ability to seamlessly integrate relevant tools and services that enhance the user experience - without adding complexity to the developer workflow. Today, we'll look at this in practice, by walking through a tutorial that integrates your Azure Static Web Apps deployed website with Azure Cognitive Search - allowing you to add custom search capability to your deployed web app in just a few steps.

What We'll Cover​

• What is Azure Cognitive Search?
• What is a Search Index?
• Add Cognitive Search to a Website
• Deploy to Azure Static Web Apps
• Exercise: Create your own search index. Deploy your app to SWA.

Make Your App Searchable!​

Today we explore adding search to a website with Azure Cognitive Search - a cloud search service that provides infrastructure, APIs, and tools, for building rich integrated search capabilities for your mobile and web applications. It even allows for custom search functionality to enhance the default experience.

We'll walk through the following example today. Want to follow along? You can grab the source code and explore it as we walk through the tutorial.

We will be using a Book Catalog example - one of the most common uses of search for a website - to demonstrate how fast it is to get this service up and running with your deployed Azure Static Web App.

This sample website provides access to a catalog of 10,000 books. The user experience goes something like this:

• The user searches the catalog by entering text in the search bar.
• As they enter text, we can use the Search Index's suggest feature to complete the text proactively.
• Once the query finishes, we display the results with a subset of details.
• Users select a book to see the details stored in the book's Search Index.

Simple, right? Let's look under the hood at how this works, and then dive into the implementation details.

What is Azure Cognitive Search?​

Azure Cognitive Search is a cloud search service that gives you, as the developer, the ability to provide rich search experiences. Architecturally, a search service sits between the external data stores that contain your unindexed data, and your client app that sends query requests to a search index and handles the response.

Cognitive Search can integrate with other Azure services that automate data ingestion/retrieval from Azure data sources, and skillsets that incorporate consumable AI from Cognitive Services, such as image and natural language processing, or custom AI that you create in Azure Machine Learning or wrap inside Azure Functions.

Once you create your Azure resource for Cognitive Search, you can access it with the following key information:

• Resource name: what you named your Cognitive Search instance.
• Index name: your resource can hold many indexes, each with its own identifiable name.
• Admin key: used to upload data into the search index
• Query key: used by the API to find data in the search index

So, we've used the term search index many times - what does that mean?

What is a search index?​

Search functionality needs data to query. In Azure Cognitive Search, this data is held in a search index. Because this particular sample is already written for you, it includes the upload of the JSON data into the search index. If you're starting from scratch, look at the Quickstart to learn how you can create an Azure Cognitive Search index with your data.

The trickiest part is mapping your data into Cognitive Search types. In order to do this, you provide a schema file that describes each data field.

Searchable title​

An example of a field in the schema file for this book catalog is the book title:

{
    "name": "title",
    "type": "Edm.String",
    "facetable": false,
    "filterable": false,
    "key": false,
    "retrievable": true,
    "searchable": true,
    "sortable": false,
    "analyzer": "standard.lucene",
    "indexAnalyzer": null,
    "searchAnalyzer": null,
    "synonymMaps": [],
    "fields": []
},

The type is a Edm.String and it uses the standard.lucene analyzer. It is searchable and retrievable (comes back in the query results).

Filter by language​

The book catalog search also allows a filter by language. This filter, known as a facet, is provided by the facetable property.

{
    "name": "language_code",
    "type": "Edm.String",
    "facetable": true,
    "filterable": true,
    "key": false,
    "retrievable": true,
    "searchable": false,
    "sortable": false,
    "analyzer": null,
    "indexAnalyzer": null,
    "searchAnalyzer": null,
    "synonymMaps": [],
    "fields": []
},

Suggest search terms as a user types​

The schema also tells the search index what fields to watch when providing search suggesters, as the user types an entry in the search box. For this sample, suggestions are based on author names and book titles.

"suggesters": [
{
    "name": "sg",
    "searchMode": "analyzingInfixMatching",
    "sourceFields": [
    "authors",
    "original_title"
    ]
}

Once the search index is created with data, you can view the data in the Visual Studio Code extension for Cognitive Search.

Add search to website​

After the search index is created with the data, you can add search functionality through the UI. Your UI passes the user's search request to your API. The API queries the search index and returns the results.

The client code provides interactive functionality:

• Provides Search component
  • Provides suggestions from the API as the user types in the search box
  • Filters the results when the user selects or deselects from a list of filters (facets).
• Provides results component, possibly paging.

The serverless code provides the following API to respond to client requests:

• Search the catalog
• Provide suggestions
• Get specific item's data

Deploy to SWA​

The sample is deployed to SWA from a GitHub action, created for you by the Visual Studio Code extension for SWA.

Once you create and deploy the sample, you need to set environment variables to connect from the serverless API to your Cognitive Search resource. Then the book catalog website is available and searchable.

Exercise: Upload data to search index​

1. Fork the GitHub sample repo, and clone it to your local computer. This is a necessary step because the GitHub action needs to be written to a repo your user account has access to.

2. Create a resource group to hold both your SWA and Cognitive Search resources.

3. Create a search index in Visual Studio Code with the Cognitive Search extension.

4. Get the admin key.

5. Set admin key and resource name in sample's bulk_insert_books.js script.

6. Don't check in these changes with git. You don't want these secrets in your public fork.

7. Install dependencies and bulk insert data in the ./bulk-insert folder:

   npm install && npm start
   

8. Your search index is ready to answer search queries.

Exercise: Deploy SWA to Azure​

1. In Visual Studio Code, create the SWA resource. This process adds a GitHub action YAML file to your fork and deploys that version to your SWA resource.

   At this point, the website should be available, but search isn't connected yet.

2. Get the query key for your search index. Your API needs these secrets (query key and Cognitive Search resource name), to answer queries from your serverless API.

3. Set the secrets for your serverless API in the Azure portal.

   Search is now connected from your API to your Cognitive Search index.

4. Use your search-enabled website to find a book.

5. Type slowly to see the suggestions based on what you enter.

6. Filter the results to a different language.

7. Select a book to see all its details.

Troubleshooting​

• Make sure you used the admin key in the upload file.
• Make sure you used the query key in the SWA config.

Next steps​

This website provides basic search functionality for books. Go beyond the basics with:

• Spell check
• Fuzzy search
• Semantics

This is just one of many samples provided in the Azure for JavaScript Developers page. Explore the Static Web Apps section and explore other Azure services you can integrated into your modern web app!

We continue our Best Practices week by looking at year another Azure Services integration option for your Azure Static Web Apps deployment. Yesterday we talked about adding search to your website using pre-trained Azure AI models. Today we'll discuss how you can use Vision AI Services.

What We'll Cover​

• What are Azure Vision Services
• How to get started building your AI applications
• How to use the JavaScript AI SDKs
• How to analyze a document using Form Recognizer
• How to deploy your APIs and Static Web App(SWA)
• Exercise Build and deploy a SWA to analyse images

Resources​

• Azure Custom Vision - Documentation
• Azure AI Fundamentals: Explore computer vision - Learn Module
• SWA Next.js - Documentation

What are Azure Vision Services?​

Azure AI Vision is part of Azure Cognitive Services - cloud-based AI services that give you Terminator-like powers.

You can take a picture and analyze it to describe the image, detect objects, landmarks and famous people or your users, read documents and scan information on an ID or a business card. All of these superpowers are available to you - an API call away - using Azure’s Cognitive and Applied AI Services. Let’s dive into what we can build and what we can customize.

Get Started building AI apps​

If you are planning to infuse your application with AI, the first place you need to look at is our Applied AI Services. Applied AI services are solving the most common use cases and build on top of our Cognitive Services. In terms of Vision related services, we have two Applied AI Services, Form Recognizer and Video Analyzer.

Azure Form Recognizer is built using Optical Character Recognition(OCR), Text Analytics and Custom Text from Azure Cognitive Services and has custom trained models for things like vaccination cards, passports and tax documentation. If you are wondering why you need Form Recognizer, you can try reverse engineering some of its features by using the Cognitive Services.

I won’t wish that for any of you and that’s why your first stop should be Applied AI Services documentation to see if your problem is solvable by any of these services. Whenever your problem is not solved or you need more flexibility, you can build with Cognitive Services, Computer Vision, Custom Vision or Face APIs.

A great way to start playing with these APIs and explore your specific use case is through Vision Studio Preview or Form Recognizer Studio preview. For example, I was wondering if I can recognize Mixed Reality devices using Computer Vision. Since these devices are very new and still not a common object, they were not recognized by our all-purpose object detection model. Before building an app, I was able to easily see that I need to train a custom model. You can check and see your logo or your product is easily recognizable or you should start training a custom model on the Studio without writing any code and find the code samples right inside the Studio.

If the object you want to detect is not recognized, you can train a custom model through customvision.ai and deploy it. You will get a custom API endpoint to call and your client implementation won’t be different than using any other service. There are couple of best practices for training a custom model. Most importantly, you need a variety of images in different contexts. For example if you want to find Waldo, you can’t just train with Waldo’s profile picture, you need to also use his pictures in a crowd.

You can read how I’ve trained my custom model and built an No Code prototype here using Power Apps AI Builder

How to use the JavaScript AI SDKs​

Using any of these APIs works pretty much the same way if you are working with an image instead of a video to analyze:

• Sign into your Azure account or sign up for $200 free credit.
• Create an Azure Cognitive Services or Specific service resource and get the key and endpoint information.
• Install the related service’s JavaScript SDK and Azure Identity SDK.
• Take a picture or upload an image.
• Initialize an AzureCredentials object using your resource key.
• Initialize a Client object with the Azure credential object & endpoint.
• Use the client’s analyze method to make an API call, wait for response.

The class and method names change, like DocumentAnalysisClient for Form Recognizer, PredictionAPIClient for Custom Vision or FaceClient for facial recognition. If you are training a custom model or using a specific model for form recognizer, you have couple of things that you will do but the most important part of it is taken care of by our SDK functionality.

How to analyze a document using Form Recognizer​

Let’s see the code in action for Form Recognizer using their new JavaScript SDK. You can start with your choice of Static Web Apps templates or add the code to your existing application.

We need to import the SDK objects and your environment variables:

import {
    AzureKeyCredential,
    DocumentAnalysisClient,
    DocumentField,
    FormRecognizerApiVersion,
    PrebuiltModels,
} from "@azure/ai-form-recognizer";

const key = process.env.FORM_RECOGNIZER_KEY || "";
const endpoint = process.env.FORM_RECOGNIZER_ENDPOINT || "";

In your async callback function that starts the analysis, like a picture upload or click event callback, you will initialize the client object and poll until you have all the results from your analysis.

async function Analyze() {
    const client = new DocumentAnalysisClient(endpoint, new AzureKeyCredential(key));

    const poller = await client.beginAnalyzeDocument("prebuilt-document", formUrl);

    const { keyValuePairs, entities } = await poller.pollUntilDone();

    //Do amazing things with the data.
}

Do something with the results, either sign in your user with their ID doc data or display the key value pairs to your user.

Deploy your app to SWA​

If you are using one of the SWA templates, all you need to do is push your code to share it with the word.

If you are not using a template, you can use the Azure Static Web Apps VS Code Extension or SWA CLI to deploy your app to an SWA resource.

If you have a lot of images and would like to batch process or if you are doing multiple things with your image, like detect objects, read the text in the image and translate, you might want to use a Azure Functions App. Thankfully creating and API for your Static Web App is one of the features of the VSCode extension. Check out my video for step by step instructions to deploy your SWA with Functions.

I hope you are inspired to enhance your applications with Azure Applied AI or Cognitive Services. Checkout the Build AI talk and demo to see what else you can do with AI.

Reach out to me on twitter if you have questions, you want to share what you build or discuss your ideas.

Exercise​

Want to explore Azure Cognitive Service integrations with your Azure Static Web App? Try walking through one of these tutorials to get hands-on experience with development:

• Build and deploy a SWA to analyse images - build a React application that analyzes an image using Azure Cognitive Services (Computer Vision) - deploy the app to Azure Static Web Apps.
• Machine Learning With Custom Vision - complete this workshop where you learn to build a model to detect dog breeds using the Custom Vision API, then deploy it to Azure Static Web Apps with an Azure Functions backend.

Week 4 focuses on Best Practices for Azure Static Web Apps. In the last two posts we explored Azure Services integrations that enhance and extend the capabilities of your deployed static website. Today, we take things in a different direction with our first Case Study - featuring KlipTok, a Twitch clip search and indexing service built by Jeff Fritz, and hosted on Azure Static Web Apps!

What We'll Cover​

• What is KlipTok?
• Why did KlipTok choose Azure Static Apps?
• How do Azure Static Apps and Blazor work together?
• Exercise: Check out the KlipTok website and see it in action.

KlipTok Makes Twitch Videos Searchable​

KlipTok is a website that I started building while streaming live on Twitch in November 2019. At the time, I wanted to build a website that would allow folks to discover Twitch clips from their favorite creators in the same way that they navigate and interact with TikTok.

Twitch is a live-streaming service that many people use to watch folks play video games. When something interesting happens on Twitch, viewers can isolate a clip (up to 60 seconds long) from the stream and share it with their friends. These clips are often fun and interesting, but typically they are not discoverable. This is KlipTok's goal - index and make those clips more available to everyone.

How does KlipTok Work?​

Behind the scenes, KlipTok monitors Twitch for new clips from streamers that are signed up with the site and indexes them. The clips are then transcribed and searchable on the site. Visitors can view, like, and comment on clips. Additionally, anyone can create playlists of clips to share with their friends.

You can read the full story behind my decision process on my blog or watch me build a subset of its features on a livestream in Nov 2020, in the video above.

After the first 18 months of running KlipTok, the application currently manages almost 12 million clips, totalling nearly 60 GB of data in the index. You can view the live dashboard at kliptok.com/status to see the current status of the application.

KlipTok Chooses Azure Static Apps​

I chose Azure Static Apps to build and deploy the KlipTok application, and to help demonstrate Blazor running at scale in a large application. This allows the application to scale the HTTP services to deliver content into the browser while delivering a high-performance experience with the Blazor application running in the browser on top of WebAssembly.

KlipTok also operates a second Azure Functions service called the 'BackOffice' that performs the synchronization of Twitch clips and other data aggregation tasks. When new channels are added to KlipTok for monitoring, the BackOffice service is triggered with a message on Azure Service Bus to add the channel and begin processing their clips for the index.

We also use this Backoffice functions app to create an ML.NET model that is used to recommend streamers to the user. The model is trained on the collection of channels that KlipTok users follow and recommends channels to users based on other users who follow the same channels. The model is updated every day with new data to help make more accurate recommendations to logged in KlipTok users.

By Twitch's terms of service, no videos are allowed to be shipped off of their platform for the first 24 hours after they are recorded. This means that the clips should be referenced and embedded from Twitch using their own clip player, saving KlipTok from having to download and store the content. KlipTok can now deliver appropriate SEO-optimized content as well as render open-graph cards appropriate for Twitter, Facebook, LinkedIn and other sites.

The KlipTok Architecture​

We do have one small problem when using Blazor Web Assembly and Azure Static Websites -- search engines and social media sites do not know how to crawl and present web assembly generated content.

To solve this, I added Azure Front Door to the site with an Azure App Service we ironically call the 'Static Site'. Azure Front Door is Microsoft’s modern cloud Content Delivery Network (CDN) - allowing us to take advantage of a globally-distributed edge network to make our content delivery faster and more efficient.

With a few rules added to Azure Frontdoor (to detect bots), users can now be redirected to the static site and KlipTok can deliver appropriate SEO optimized content along with the open-graph cards for Twitter, Facebook, LinkedIn and other social sharing sites.

Why Azure Static Web Apps?​

When KlipTok was originally conceived, I wanted to spend very little money and allow the site to scale easily with new traffic as it grows. As a C# and Blazor developer, this gave me the perfect intersection of my favorite technologies, keep costs low, and start to develop an application that demonstrates the capabilities of Blazor with a VERY large dataset.

Over time, the system components of KlipTok have matured and been swapped out. Azure Table Storage gave way to MySQL and has been since replaced by RavenDb. The Azure Functions were originally communicating using Azure Queues, and many of them are now using Azure Service Bus.

This maturing of the system components has allowed me to build and understand how other customers are using Azure and how we can improve the product to make developers of systems like KlipTok more productive.

Using Azure Static Web Apps makes it easier for developers to integrate other Azure services - which then makes it possible for me to evolve KlipTok's architecture and capabilities quickly, to reflect changing needs.

SWA & Blazor: Made for each other​

As a developer, I've been very happy with the combination of Blazor and Azure Static Web Apps. The ability to build a Blazor application and know that I will always have APIs scaling to meet my customers needs is a huge plus.

Blazor Web Assembly uses an HttpClient to communicate with web servers;in the case of an Azure Static Web App it communicated with an HTTP triggered function. This allows me to dramatically simplify the definition and interaction of front-end code and the back-end code.

For example: when a user clicks the Like button on a clip, the Blazor application can post a message to the hosted function to increment the like count. This function then updates the like count in RavenDb, then updates the UI with the new like count. The Blazor application needn't wait for the function to complete before updating the UI - it can just add or subtract one from the like count.

Summary​

KlipTok has been an absolute joy to build and the journey to deliver it has been a great success. I'm very excited to continue working on KlipTok and continue to grow the application while discovering and demonstrating more cool Blazor and Azure features. Have questions or comments? Find me on Twitch

Exercise​

• Want to see this Azure Static Web App in action? Click over to KlipTok and login with your Twitch account! Then browse the site to have KlipTok start showing you clips from your favorite creators.
• Want to explore building your own Azure Static Web App with Blazor? Check out my earlier blog post for a great exercise where you'll start with my open-source project - Fritz's Really Cool Hats - to customize, build and deploy a Blazor-powered app to Azure Static Web Apps.

All week, we'll explore end-to-end development workflows with Azure Static Web Apps as one component that is integrated with other services to deliver an enhanced modern web application experience.

The default Azure Static Web Apps architecture separates the web application into two components: static assets (served from global content distribution services) and dynamic API endpoints (implemented using serverless architectures). In our API-enabling SWA post, we focused on Managed Functions, where the Azure Static Web Apps service configures and manages your Azure Functions Deployment.

Today, we'll explore the other option Bring Your Own Functions - where you can use pre-existing (or independently developed) Azure Functions applications and manage their deployment separately.

What We'll Cover​

• What is "Bring Your Own Functions" (BYOF)?
• Benefits of BYOF over Managed Functions
• Switching from Managed Functions to BYOF
• Resources: Building Serverless apps with Azure Functions
• Exercise: Complete this learning module, add real-time updates to your SWA!

What does "Bring Your Own Functions" (BYOF) mean?​

In our API-enabling SWA post, we mentioned that the Azure Static Web App can implement Serverless API using Azure Functions in two ways:

• Managed Functions - where the Azure Static Web Apps service configures and manages your Azure Functions deployment.
• Bring Your Own Functions - where you use a pre-existing Azure Functions application and manage the deployment yourself.

The second option means that you build and deploy a serverless application using Azure Functions that exists independent of your Azure Static Web App deployment. These applications can make use of the full Azure Functions feature set without any of the limitations imposed for Managed Functions in SWA. All you need to do is configure the Static Web App service to use this new serverless API endpoint.

Why "Bring Your Own Functions"?​

Bring Your Own Functions is a power feature of Azure Static Web Apps that lets you link existing Functions apps and allows you to avoid the restrictions of Managed Functions. This means you can:

• Implement and run functions in any language using custom handlers.
• Use triggers and bindings to create complex workflows with ease.
• Implement Durable Functions that remain stateful in serverless contexts.
• Use any other Azure Functions features and adopt best practices.

These kinds of capabilities become critical when you deploy real-world applications at scale. Note that Azure Static Web Apps has two hosting plans: free and standard where the Free tier supports only Managed Functions. To take advantage of the power of "Bring Your Own Functions" you need to be on the standard plan.

Linking an existing Functions app​

Using an existing Functions app in Static Web Apps is easy - all your have to do is link the two apps together. Once you create the link, then a Functions app published under the following URL:

https://my-functions-app.azurewebsites.net/api/data

...is now also available under the api route in your static web app.

For instance:

https://red-sea-123.azurestaticapps.net/api/data

Linking an existing Functions app is a two step process: (1) Update the staticwebapp.config.json file, and (2) Link the apps via the Azure portal.

1. Update the configuration​

Edit your site's staticwebapp.config.json file to make these changes:

• Set the api_location value to an empty string ("")

2. Link apps via the Azure portal​

Navigate to your static web app in the Azure portal and make these changes:

• Click on Functions in the Settings menu
• Click Production in the Environment dropdown
• Click Link to Function app next to the Functions type dropdown
• Select your subscription from the Subscription dropdown
• Select your Functions app name from the Function App dropdown
• Click the Link button

Now your Functions app is linked to your website and is available under the api route for your Static Web App!

Resources​

1. Overview​

Are you new to the whole idea of serverless applications and a Functions-based backend? Watch this video overview of Azure Functions - then check out the developer guide.

2. Quickstart​

Want to get a quickstart with Azure Functions? You can code your functions in C#, Java, JavaScript, PowerShell, Python, TypeScript and more (e.g., Go, Rust). For example, you can create JavaScript Functions apps in the following ways:

• Using Visual Studio Code
• Using Commandline Tools
• Using an ARM Template = JSON configuration file

3. Learning Path​

Want a more comprehensive tour of Azure Functions features and capabilities, with hands-on modules? Try the Create Serverless Applications learning path. It has 11 modules covering both core concepts and usage examples.

Exercise​

Complete this learning moduleto learn how to use Azure SignalR to get real-time updates to your app using Azure Functions. Then put that learning to use by updating one of your existing SWA projects to use this capability.

In an earlier example this week, we looked at a real-world case study with KlipTok, involving Azure Static Web Apps integration with multiple backend services, to deliver the desired user experience. Today we look at another great example of an end-to-end development workflow that involves multiple service integrations - this time with a focus on deliver a rich video conferencing web application experience. Let's learn how to build this with a workflow that involves Azure Static Web Apps, Azure Functions, Azure CosmosDB - and Azure Communications Services (ACS).

What We'll Cover​

• What is Azure Communications Services (ACS)?
• The Video Conference Authentication Workflow
  • Azure Static Web Apps for social authentication
  • Azure CosmosDB to store ACS identity information
  • Azure Functions to map social auth to ACS identity
• A Static Web App - hosting a Metaverse? 🤯
• Exercise Deploy the sample yourself following the step-by-step tutorial

What is Azure Communications Services (ACS)?​

Azure Communication Services (ACS) is a set of rich communication, video, and SMS APIs to deploy your applications across any device, on any platform. If you want to enable emails, chat, audio/video conferencing, phone calls or SMS inside an existing app, this service is right for you. You can view it as your building blocks to create your own custom version of Microsoft Teams, it uses the same underlying infrastructure. This CPaaS (Communications Platform As A Service) will manage scalability, quality & availability of this service for you. This platform is also built on top of our secure and compliant cloud.

Watch this short video for a quick introduction 👇🏼

Of course, this service comes with a price. You can find the cost of each service by visiting Azure Communication Services pricing | Microsoft Azure.

ACS exposes its services via various SDKs: Azure Communication Services – Samples and Tools available for JavaScript, .NET, Java, Android, iOS & Python developers.

You can also optionally use this on top of the ACS UI library: Overview – Page ⋅ Storybook which consists of React-based components implementing the Microsoft Fluent Design to help you build visually engaging web apps. The best sample mixing all of these concepts is Group calling hero sample – An Azure Communication Services sample overview.

To give you a brief idea, watch this 2 min video tutorial that shows you how to get the internal ACS authentication token to connect to its infrastructure. I can then join an existing Teams meeting using a simple web page and the ACS JavaScript SDK:

Want to follow along at home? You simply need to:

• Create an Azure Communication Services resource in your Azure Portal
• Navigate to https://aka.ms/acsquicktest and follow the video tutorial above.

You’ll discover that, by default, Azure Communication Services provides the basic authentication & identity layer. But you need to build on top of it to connect your own identity platform. Let’s see how to do that, next!

Building an authentication layer with Azure Function, CosmosDB & Static Web App​

1. Azure Static Web Apps - social authentication​

Well, it turns out that SWA provides an awesome out of the box authentication experience. To know more about it, please read: Authentication and authorization for Azure Static Web Apps. In seconds, without any additional code required, you’ll have an authentication layer provided to you!

We’re going to use it as our front end to welcome and authenticate our users.

2. Azure Functions - map to ACS identity​

Then, we will map their social account identity with the internal ACS identity via an Azure Function. The Azure Function will store the mapping into a small CosmosDB table. Here’s the flow.

First, you’ll land on a page asking you to choose your favorite social provider:

Then, once authenticated, you’ll be directly connected to the Azure Communication Services infrastructure. No need to generate a token or whatever, the Azure Function took care of it. I’ve been using my Twitter account in this screenshot for instance:

You see that the UI shows how my Twitter account, davrous@twitter, is mapped to the internal ACS user ID 8:acs:4ba98fcc… that you should normally not share to the users of course 😉.

Thanks to that, you’re ready to call friends and colleagues immediately or join a Teams meeting via simply using their social account email address as the person to call.

3. Azure Functions + CosmosDB Binding​

Let’s have a look to the Azure Function code enabling this scenario. First, you can see in the function.json file that I’m using the CosmosDB binding feature. To know more about this feature:

• Azure Cosmos DB input binding for Functions 2.x and higher
• Azure Cosmos DB output binding for Functions 2.x and higher

In a nutshell, via a simple declaration in the function.json file, you have a simple data access layer available in your Azure Function code for free.

If you look into my json file, I’m defining a route under users/{email}/{lookup:bool?} that will be exposed under 2 functions in my Azure Function: setUser as the output binding (to write or update into CosmosDB) and getUser as the input binding (to read from CosmosDB).

In this declaration file, I’m also asking the Azure Function to use the CosmosDB database named “ACS” with the table named “users” using “email” parameter as the partition key.

getUser will be called with a first required parameter which is an email address associated to the ACS internal identity. It has a second optional parameter which is a boolean. This asks to the Azure Function to do a simple resolve query to return the internal ACS id associated with the email address. It’s useful when you’d like to call someone on ACS by simply providing his email address rather than being forced to know its internal ACS identity (starting with 8:acs:xxx).

setUser simply create a new record or update it.

You can find the complete source code of the Azure Function there: acsauth/index.ts at main · davrous/acsauth (github.com).

The first block is simply doing the resolve logic I was mentioning just before. The second block is first checking if the user has already been created in the CosmosDB table and if the ACS token is still valid. Indeed, ACS tokens are valid for 24 hours only. If the user doesn’t exist or if its token has expired, we’re using the ACS JavaScript SDK to create a new identity & authentication token to map it to the email address.

If you’re interested in the ACS identity concepts, please read:

• Identity model - An Azure Communication Services concept
• Quickstart - Create and manage access tokens - An Azure Communication Services quickstart

4. CosmosDB - stores ACS identity data​

Now, let’s have a look to what’s stored in the CosmosDB table thanks to the Azure Portal:

You can find all the required information for my scenario:

• id: an email address coming from the social network, which is my partition key and my primary key for my requests
• userId: the associated internal ACS identity in the form of 8:acs:xxxx.
• userToken: the associated internal ACS authentication token required to be able to connect to the ACS infrastructure
• expiresOn: when the ACS authentication token will expire

The beauty of the Azure Function binding feature is that I didn’t have to write any code to manage the reading or writing part of the records. It can even update an existing record if needed.

With few lines of code, I’ve been able to create a small authentication layer on top of ACS to create users mapped to ACS internal identity. With the out of the box Static Web App authentication experience, I didn’t even need to write any code to authenticate users with their social identity!

A Static Web App hosting a Metaverse? 🤯​

In the same sample, I’ve been building on top of the architecture described just above a small metaverse using Babylon.js, an open source & free WebGL engine I’ve been contributing to. The logic is identical to what I’ve described up to now.

Thanks to the SWA, I’m authenticating the user using his social profile. But then, I can do the video call to another ACS user or someone in Teams from a 3D scene. And everything is waayyy cooler inside a 3D scene, right?

But wait, there’s even better. You can experience this Babylon.js scene in VR thanks to its native WebXR support! To give you an idea, here’s a video where I’m using my Valve Index to call my girl friend in Teams so we can visit this museum together.

If you’re interested in WebXR, I’ve written a full article on what you can build with it sharing lot of my samples: From gaming to metaverses, building WebXR apps with Babylon.js – David Rousset (davrous.com).

Exercise​

If you’d like to play and learn from this sample mixing ACS, SWA, Azure Function, CosmosDB & Babylon.js, you can deploy it in less than 10 minutes by following the step-be-step tutorial available in this associated repo: davrous/acsauth: Deploy in less than 10 min an Azure Communication Services sample to be shared & tested with your colleagues & friends.

Enjoy and see you in the metaverse! 😊

We're at the last post of the series, so let's close the loop to where we started on Day 1. We started by talking about End-to-End Developer Experiences built on Azure Static Web Apps - and continued with a series of posts exploring various Azure service integrations that showcase this vision. Wouldn't it be great if you could have one end-to-end development example that you could use as a starter for your next prototype? Let's end this week with the perfect example. Today we'll look at an end-to-end developer workflow for a full-stack app:

• Front-end built with React and Redux Toolkit
• Back-end built with Azure Functions
• Deployed to the cloud with Azure Static Web Apps
• With a MongoDB database hosted in Cosmos DB, accessed using Mongoose
• (Optionally, with Playwright testing)

What We'll Cover​

• Building a Full-Stack App
• Why use Mongoose?
• Why use Redux Toolkit?
• Build: Implement and deploy the React/Mongoose template
• Exercise: Add your own features

Building a Full-Stack App with SWA​

In the first week of this series, we looked Building Static Web Apps using an existing starter template and learned about options for working with Azure Static Web Apps:

1. using VS Code - if you prefer an IDE
2. using Azure CLI - if you prefer the command-line
3. using Azure Portal - if you prefer a browser-based workflow
4. using Azure Static Web Apps CLI - if you prefer a unified develop-deploy tool

The default starter templates (for vanillaJS, React, Angular, Blazor, Vue) use a simple front-end application to validate your local development setup, and familiarize you with the automated build/deploy workflow setup by Azure Static Web Apps.

Today we'll look at something different - a mongoose-starter template for building a full-stack application with a React/Redux front-end, a serverless back-end (using Azure Functions) and a NoSQL database (using Azure CosmosDB API for MongoDB) that works seamlessly with the popular mongoose client.

Learn more about creating full-stack apps using this technology stack, in this video:

Why use Mongoose?​

When accessing a data store you can either use APIs to interact directly with the backend or use a library which can provide additional functionality. Many developers prefer to use a library as it allows them to focus more on creating their code and logic while offloading some of the work. Mongoose is just such a library.

Mongoose is an Object-Database-Mapper (ODM) which allows you to define the objects you need to store in a NoSQL database. Mongoose can be used with any database which supports MongoDB APIs, which Cosmos DB does. With Mongoose you can create schemas for your data, enforce validation, and streamline the process of interacting with your data.

Why use Redux Toolkit?​

Redux is the most popular tool for managing state in a React application. Redux Toolkit helps create projects which use Redux by providing an additional framework for some of the most common tasks when using Redux. Redux Toolkit includes functions to streamline the process of creating reducers and updating and accessing state.

Quickstart: Using the React/Mongoose template​

To help jump start your development process, we'll use the mongoose-starter template built on the following libraries and tools:

• React
• Redux Toolkit
• Mongoose
• Node-config
• SWA CLI

The template is a todo application and contains models for items and lists (which contain the items). It uses GitHub authentication through Azure Static Web Apps. To support local development, a devcontainer.json file is included use a dev container.

Follow this tutorial to build and deploy the full-stack application to Azure Static Web Apps by completing the following steps:

• create the Cosmos DB server
• create a new repository from the template
• create the Azure Static Web App
• configure the Azure Static Web App
• use the site

Watch this segment to walk interactively through the process of using the mongoose-starter template build/deploy the basic project to Azure Static Web Apps.