add website docs

dictionary.txt

@@ -252,6 +252,8 @@ Trivy's
 KMS
 deployable
 VMs
+CDN
+subdirectories
 [0-9]+px
 ^.+[-:_]\w+$
 [a-z]+([A-Z0-9]|[A-Z0-9]\w+)

docs/architecture/websites.mdx

@@ -0,0 +1,142 @@
+---
+description: 'Learn how Nitric provisions and manages websites with Terraform and Pulumi across AWS, GCP, and Azure.'
+---
+
+# Websites
+
+## 1. System Context
+
+**Developers** use Nitric to define required websites within their application.
+
+- App code uses the [Website resource](/websites) defined in `nitric.yaml` to specify the websites and their configurations.
+- Developers can configure base path, index pages, error pages, and other settings in their `nitric.yaml` file.
+- When a website is defined, a single CDN endpoint is automatically created to serve the website content globally, including APIs as proxies.
+
+**Operations** use default or overridden IaC (e.g., Terraform modules) to provision the necessary resources for their target cloud.
+
+<details>
+  <summary>Example AWS Provider</summary>
+
+- **AWS S3** serves as the storage backend for static files (e.g., HTML, CSS, JS, images).
+- **AWS CloudFront** is used to distribute the website globally and serve as a single entry point for the whole application.
+- **AWS IAM** providers roles for access to the Website bucket
+
+```mermaid
+flowchart TD
+    Developer["Developer"]
+    NitricUp["nitric up"]
+    S3["AWS S3 Bucket"]
+    CloudFront["AWS CloudFront"]
+    Rewrite["AWS API Gateway"]
+
+    Developer -->|Deploy| NitricUp
+    NitricUp -->|Upload Assets| S3
+    NitricUp -->|Create CDN| CloudFront
+    CloudFront -->|Serve Static Files| S3
+    CloudFront -->|Rewrite /api/* to API| Rewrite
+
+classDef default line-height:1;
+classDef edgeLabel line-height:2;
+```
+
+</details>
+
+<details>
+  <summary>Example Azure Provider</summary>
+- **Static Website in Azure Blob Storage** serves as the storage backend for static files (e.g., HTML, CSS, JS, images).
+- **Azure Front Door** is used to distribute the website globally and serve as a single entry point for the whole application.
+
+```mermaid
+flowchart TD
+    Developer["Developer"]
+    NitricUp["nitric up"]
+    Storage["Azure Storage"]
+    FrontDoor["Azure Front Door"]
+    Rewrite["Azure API Management"]
+
+    Developer -->|Deploy| NitricUp
+    NitricUp -->|Upload Assets| Storage
+    NitricUp -->|Create CDN| FrontDoor
+    FrontDoor -->|Serve Static Files| Storage
+    FrontDoor -->|Rewrite /api/* to API| Rewrite
+
+classDef default line-height:1;
+classDef edgeLabel line-height:2;
+```
+
+</details>
+
+## 2. Sequence
+
+### Build Sequence
+
+Below is the sequence of events that occur when a developer registers a website with Nitric:
+
+```mermaid
+sequenceDiagram
+    participant Config as nitric.yaml
+    participant CLI as Nitric CLI
+    participant Provider as Nitric Provider<br>(plugin)
+    participant IAC as IaC (e.g. Terraform)
+
+    CLI->>Config: Parse website configuration
+    CLI->>Provider: Forward Nitric Spec
+    Provider->>IAC: Provision Website
+    Provider->>IAC: Provision IAM
+```
+
+## 3. Component
+
+### Website Module
+
+- Deploys website assets to a cloud-based storage solution for flexible and scalable hosting.
+- Configures a distribution layer to serve the site globally, rewriting API endpoints to `/api/{apiName}` for consistent routing.
+- Automatically invalidates the cache based on file changes, ensuring users always receive the latest content.
+
+## 4. Code
+
+**Developers** write yaml configuration to define the website and implement logic to serve static files.
+
+### Nitric website configuration - nitric.yaml
+
+```yaml
+name: service-name
+services:
+  - match: ./services/*.js
+    start: npm run dev:services $SERVICE_PATH
+    runtime: node
+runtimes:
+  node:
+    dockerfile: ./node.dockerfile
+    args: {}
+# The website configuration
+websites:
+  - basedir: ./my-website
+    index: index.html
+    error: 404.html
+    build:
+      command: npm run build
+      output: ./dist
+    dev:
+      command: npm run dev -- --port 4322
+      url: http://localhost:4322
+```
+
+### Access an API from the website frontend
+
+```javascript
+async function fetchData() {
+  // due to apis being served from the same domain thanks to rewrites, no CORS is required
+  const response = await fetch('/api/main/hello')
+  const data = await response.json()
+  console.log(data)
+}
+```
+
+**Operations** will use or extend the Nitric infrastructure modules, including both Terraform and Pulumi:
+
+- Terraform Modules:
+  - Not yet available
+- Pulumi Modules:
+  - [AWS Website Pulumi Module](https://github.com/nitrictech/nitric/blob/main/cloud/aws/deploy/website.go)
+  - [Azure Website Pulumi Module](https://github.com/nitrictech/nitric/blob/main/cloud/azure/deploy/website.go)

docs/get-started/foundations/projects/configuration.mdx

@@ -234,3 +234,61 @@ runtimes:
     args:
       GO_VERSION: 1.16
 ```
+
+### `websites` (optional)
+
+A list of [website](/websites) types that make up your project. Websites are used to serve static files and assets.
+
+```yaml
+websites:
+  - basedir: ./my-website
+    path: /
+    index: index.html
+    error: 404.html
+    build:
+      command: npm run build
+      output: ./dist
+    dev:
+      command: npm run dev
+      url: http://localhost:4322
+```
+
+#### `basedir`
+
+The base directory to search for website assets. If not provided, the base directory is the root of the project. This is useful when you want to group websites under a specific directory or you're working with a monorepo.
+
+#### `path`
+
+The path to serve the website at. If not provided, the default is `/`. This is useful when you want to serve multiple websites under different paths.
+
+#### `index`
+
+The name of the index file to serve. If not provided, the default is `index.html`.
+
+#### `error`
+
+The name of the error file to serve. If not provided, the default is `404.html`.
+
+#### `build`
+
+A map of build configuration options for the website. This is used to build the website assets before deployment.
+
+##### `command`
+
+The command to build the website assets. This command will be executed in the base directory of the website.
+
+##### `output`
+
+The output directory for the built website assets. This is relative to the base directory of the website.
+
+#### `dev`
+
+A map of development configuration options for the website. This is used to run the website in development mode.
+
+##### `command`
+
+The command to run the website in development mode. This command will be executed in the base directory of the website.
+
+##### `url`
+
+The URL to access the website in development mode. This is used to configure the Nitric CLI to proxy requests to the website during local development.

docs/get-started/foundations/projects/local-development.mdx

@@ -61,6 +61,7 @@ The Nitric CLI also hosts a Local Development Dashboard, which provides a graphi
 - **Topics**: View topics and subscriptions, and publish messages to topics.
 - **Secrets**: View and manage your application secrets.
 - **WebSockets**: Dive deep into connection details, connecting, and sending messages.
+- **Websites**: View your websites.
 
 Many of these features make it possible to build and testing modules of your application in isolation. For example, you can could create and test a topic and subscriber without needing to first write the publisher.
 

docs/providers/mappings/aws/websites.mdx

@@ -0,0 +1,24 @@
+---
+description: 'How Nitric deploys Websites to AWS'
+---
+
+# AWS Resources - Websites
+
+Nitric Websites are deployed to AWS using [Amazon S3](https://aws.amazon.com/s3/) and [Amazon CloudFront](https://aws.amazon.com/cloudfront/).
+
+## AWS Resources
+
+The following resources are created when deploying Websites to AWS:
+
+- S3 Bucket
+- IAM Policies and Permissions
+- CloudFront Distribution
+- CloudFront Functions
+
+## Deployment
+
+During deployment the Nitric CLI creates a bucket for your website assets and a CloudFront distribution to serve them:
+
+- The declared website is created in S3
+- A CloudFront distribution is created to serve your website and rewrite all APIs to `/api/{apiName}` using CloudFront Functions
+- Cache invalidation is automatic based on changed files

docs/providers/mappings/azure/websites.mdx

@@ -0,0 +1,23 @@
+---
+description: 'How Nitric deploys Websites to Azure'
+---
+
+# Azure Resources - Websites
+
+Nitric Websites are deployed to Azure using [Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/) and [Azure Front Door](https://azure.microsoft.com/en-us/services/frontdoor/).
+
+## Azure Resources
+
+The following resources are created when deploying Websites to Azure:
+
+- Blob Storage Account with Static Website
+- Front Door Endpoint (with Front Door Classic)
+- Delivery Rules for API rewrites
+
+## Deployment
+
+During deployment the Nitric CLI creates a storage account for your website assets and a Front Door distribution to serve them:
+
+- The declared website is created in Blob Storage
+- A Front Door endpoint is created to serve your website and rewrite all APIs to `/api/{apiName}` using Delivery Rules
+- Cache invalidation is automatic based on changed files

docs/reference/preview-features/index.mdx

@@ -17,6 +17,7 @@ Each preview feature will have its own documentation page, which will include in
 | [docker-providers](/providers/custom/docker) | CLI v1.39.0                                                                                     | [feedback](https://github.com/nitrictech/nitric/issues/605) |
 | [sql-databases](/sql)                        | CLI v1.42.0<br/>AWS Provider v1.6.0<br/>Azure Provider v1.9.0<br/>AWS Terraform Provider v1.8.0 | [feedback](https://github.com/nitrictech/nitric/issues/684) |
 | [batch-services](/batch)                     | CLI v1.54.0<br/>AWS Provider v1.14.0<br/>GCP Provider v1.14.0                                   | [feedback](https://github.com/nitrictech/nitric/issues/685) |
+| [websites](/websites)                        | CLI v1.58.0<br/>AWS Provider v1.18.0<br/>Azure Provider v1.18.0                                 | [feedback](https://github.com/nitrictech/nitric/issues/748) |
 
 ## Released Preview Features