DOCSEARCHbyAlgolia
Submit Docs

Azure Static Web Apps CLI

repository·main·Indexed 20 days ago

https://github.com/azure/static-web-apps-cli

The Azure Static Web Apps CLI (@azure/static-web-apps-cli) provides tools for developing and deploying static web applications. The repository includes reference implementations and templates for various frameworks, including Sapper, Angular, Astro (with React, Vue, Svelte, Solid.js, Preact, and Lit), and Aurelia, as well as samples for C# functions using HttpTrigger.

Tokens
66.7K
Snippets
300
Records
381
Agent score
70%

What's inside Azure Static Web Apps CLI

  1. What is Stencil?

    main

    Stencil is a compiler for building fast web apps using Web Components. It combines TypeScript, JSX, a tiny virtual DOM layer, efficient one-way data binding, and an asynchronous rendering pipeline to generate 100% standards-based Web Components.

    Key features include:

    • Standards-based: Generates Web Components that run in any browser supporting the Custom Elements v1 spec.
    • Framework Agnostic: Components work in any major framework or with no framework at all.
    • Advanced Capabilities: Supports Server Side Rendering (SSR) without a headless browser, pre-rendering, and objects-as-properties.

  2. What is the Static Web Apps (SWA) CLI?

    main

    The Static Web Apps (SWA) CLI (command swa) is an open-source command-line tool designed to streamline the local development and deployment workflow for Azure Static Web Apps. It allows developers to emulate the Azure Static Web Apps environment locally, including routing, authentication, and API integration, before deploying to production.

    Key Features:

    • Asset Serving: Serve static app assets or proxy requests to your local application development server.
    • API Proxying: Serve API requests or proxy to APIs running in Azure Functions Core Tools.
    • Auth Emulation: Emulate authentication and authorization using mock responses.
    • Configuration Emulation: Emulate Static Web Apps configuration for routing and role-based access control (RBAC).
    • Deployment: Streamline the workflow from local development to deploying directly to Azure Static Web Apps.

  3. What is VuePress?

    main

    VuePress is a documentation-focused tool composed of two main parts:

    1. A minimalistic static site generator: This includes a Vue-powered theming system and a Plugin API.
    2. A default theme: Optimized specifically for writing technical documentation.

    How it works:

    • Static Generation: Each page is pre-rendered into static HTML, ensuring high loading performance and SEO friendliness.
    • Hydration: Once the page loads in the browser, Vue.js takes over the static content, transforming it into a full Single-Page Application (SPA).
    • Navigation: Additional pages are fetched on demand as users navigate the site.

  4. What is Slate?

    main

    Slate is an API documentation generator designed to create responsive, intelligent, and beautiful API documentation. It uses a two-column layout inspired by Stripe and PayPal, where API descriptions are placed on the left and code examples are placed on the right.

    Key characteristics include:

    • Single-page documentation: The entire documentation resides on one page, with the browser's hash updating automatically as you scroll to maintain linkability.
    • Markdown-based: All documentation, including code samples, is written in Markdown.
    • Multi-language code tabs: You can provide code samples in multiple programming languages by using standard Markdown code blocks with language identifiers.
    • Automatic Table of Contents: A smoothly scrolling table of contents is provided on the left side of the page.
    • RTL Support: Full support for right-to-left languages like Arabic, Persian, and Hebrew.

  5. Overview of Azure Static Web Apps CLI

    main

    The Azure Static Web Apps CLI (SWA CLI) is a local development tool designed to emulate the capabilities of the Azure Static Web Apps cloud service. It allows developers to simulate the production environment locally before deploying.

    Key capabilities include:

    • Serving static app assets or proxying to a local app development server.
    • Serving API requests or proxying to APIs running in Azure Functions Core Tools.
    • Emulating authentication and authorization.
    • Emulating Static Web Apps configuration, including routing and ACL roles.
    • Deploying applications directly to Azure Static Web Apps.

  6. TypeScript and Type Checking configuration

    main

    This template uses specific configurations to manage type information:

    • Type Information: Instead of using compilerOptions.types in jsconfig.json or tsconfig.json (which can exclude other types), the template uses a global.d.ts file with triple-slash references. This ensures the project accepts type information from the entire workspace while adding svelte and vite/client types.
    • JavaScript Type Checking: The JS template enables checkJs to provide advanced typechecking out of the box, helping catch accidental variable type changes. This can be disabled if you prefer a more dynamic JavaScript experience.

  7. Preserve component state during HMR

    main

    Hot Module Replacement (HMR) state preservation is disabled by default in svelte-hmr and @sveltejs/vite-plugin-svelte due to unpredictable behavior.

    If you have state that must be retained during HMR, do not rely on local component state. Instead, move that state into an external store that will not be replaced by HMR.

    // store.js
// An extremely simple external store
import { writable } from "svelte/store";
export default writable(0);

  8. Understand Docusaurus content structure and configuration

    main

    The documentation site follows a standard Docusaurus structure:

    Content Directories

    • blog/: Posts with index page, tags, and RSS feed (Note: The blog feature is deactivated by default in this project).
    • docs/: Tutorials and documentation with sidebars and navigation.
    • src/pages: Standalone pages that map directly to routes.
    • static/: Static assets served as-is.

    Configuration and Customization

    • docusaurus.config.js: The primary configuration file for the navbar, footer, plugins, and site features.
    • sidebars.js: Used to explicitly specify sidebar contents.
    • src/css/custom.css: Used to customize the theme palette and implement sitewide CSS changes.
    • src/components/HomepageFeatures/index.js: Used to customize the landing page features grid.
    • src/components/index.js: Used to customize the landing page layout.

    Content Creation Guidelines

    • Tutorials/Step-by-step: Add files under docs/X/Y (where X is the tutorial and Y is the step). Use docs/X/_category_.json to define metadata and placement.
    • Standalone Pages: Add a file as src/pages/X.md. The filename X determines the route name.

  9. Structure a Wintersmith blog project

    main

    A Wintersmith blog project follows a specific directory structure to manage configuration, content, and templates.

    • config.json: Contains site-wide configuration.
    • contents/: The root for all content.
      • articles/: Each article resides in its own subdirectory containing an index.md file.
      • authors/: Contains JSON metadata for authors (e.g., the-wintersmith.json).
      • css/: Site stylesheets.
    • plugins/: Contains plugin logic (e.g., paginator.coffee).
    • templates/: Pug templates used for rendering (e.g., article.pug, layout.pug).
    • views/: Logic for views, such as listing articles.

    Note: Articles are sorted by date. Pagination settings (like items per page) are managed in config.json and can be influenced by plugins like paginator.coffee.

    ├── config.json               <- site configuration
├── contents
│   ├── about.md
│   ├── archive.json
│   ├── articles              <– each article has its own directory
│   │   ├── another-test
│   │   │   └── index.md
│   │   ├── bamboo-cutter
│   │   │   ├── index.md
│   │   │   └── taketori_monogatari.jpg
│   │   ├── hello-world
│   │   │   └── index.md
│   │   ├── markdown-syntax
│   │   │   └── index.md
│   │   └── red-herring
│   │       ├── banana.png
│   │       └── index.md
│   ├── authors               <- author metadata
│   │   ├── baker.json
│   │   └── the-wintersmith.json
│   ├── css
│   │   └── main.css
│   └── feed.json
├── plugins
│   └── paginator.coffee      <- paginator plugin
├── templates
│   ├── archive.pug
│   ├── article.pug
│   ├── author.pug
│   ├── feed.pug
│   ├── index.pug
│   └── layout.pug
└── views
    └── articles.coffee       <- view that lists articles

  11. Manage static assets and images

    main

    Static Assets

    Files in the static directory are served publicly from the root URL. For example, static/image.jpg is available at /image.jpg.

    To manage caching in a service worker, import the generated file list:

    import { files } from "@sapper/service-worker";

    Images in src/node_modules/images

    Images placed in src/node_modules/images can be imported directly into your code. They receive hashed filenames for efficient CDN caching:

    import 'images/<filename>'
    import { files } from "@sapper/service-worker";

  12. How the SWA CLI architecture works

    main

    The SWA CLI operates using a Reverse Proxy as its core component. The proxy intercepts incoming HTTP requests and routes them to the appropriate internal service based on the URL path:

    • /.auth/** requests: Forwarded to the Authentication Server (Emulator) to simulate auth flows and return mock responses.
    • /api/** requests: Forwarded to the Serverless API server (typically running via Azure Functions Core Tools) for local API testing.
    • /** (all other requests): Forwarded to the Static Content Server, which serves your HTML, CSS, JS, and media assets.

    :::warning Always test on Azure for production! The SWA CLI uses emulated services. Because emulated behaviors may differ from real-world Azure services, always validate your final application in Azure preview or production environments.