diff --git a/docs/architecture/websites.mdx b/docs/architecture/websites.mdx index c954a627f..fcf7dcef0 100644 --- a/docs/architecture/websites.mdx +++ b/docs/architecture/websites.mdx @@ -10,7 +10,7 @@ description: 'Learn how Nitric provisions and manages websites with Terraform an - 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. +- When a website is defined, a single CDN endpoint is automatically created to serve the website content globally, including APIs and websockets as proxies. **Operations** use default or overridden IaC (e.g., Terraform modules) to provision the necessary resources for their target cloud. @@ -34,6 +34,7 @@ flowchart TD NitricUp -->|Create CDN| CloudFront CloudFront -->|Serve Static Files| S3 CloudFront -->|Rewrite /api/* to API| Rewrite + CloudFront -->|Rewrite /ws/* to Websocket| Rewrite classDef default line-height:1; classDef edgeLabel line-height:2; @@ -59,6 +60,7 @@ flowchart TD NitricUp -->|Create CDN| FrontDoor FrontDoor -->|Serve Static Files| Storage FrontDoor -->|Rewrite /api/* to API| Rewrite + FrontDoor -->|Rewrite /ws/* to Websocket| Rewrite classDef default line-height:1; classDef edgeLabel line-height:2; @@ -122,20 +124,31 @@ websites: url: http://localhost:4322 ``` -### Access an API from the website frontend +### Access an API or Websocket from the website frontend ```javascript +// API Example 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) } + +// Websocket Example +const ws = new WebSocket('/ws/chat') + +ws.onmessage = (event) => { + console.log(event.data) +} + +ws.send('Hello, server!') ``` **Operations** will use or extend the Nitric infrastructure modules, including both Terraform and Pulumi: - Terraform Modules: + - [AWS Website Terraform Module](https://github.com/nitrictech/nitric/blob/main/cloud/aws/deploytf/.nitric/modules/website/main.tf) - [Azure Website Terraform Module](https://github.com/nitrictech/nitric/blob/main/cloud/azure/deploytf/.nitric/modules/website/main.tf) - [Google Cloud Website Terraform Module](https://github.com/nitrictech/nitric/blob/main/cloud/gcp/deploytf/.nitric/modules/website/main.tf) - Pulumi Modules: diff --git a/docs/guides/deno/byo-deep-research.mdx b/docs/guides/deno/byo-deep-research.mdx index 31791da21..7ca79c5b1 100644 --- a/docs/guides/deno/byo-deep-research.mdx +++ b/docs/guides/deno/byo-deep-research.mdx @@ -1,7 +1,6 @@ --- title_seo: 'Building Your Own Deep Research System with Nitric' description: 'Learn how to build a simple research system using Nitric that can be tested locally and deployed to production' -author: tim_holm languages: - typescript tags: diff --git a/docs/providers/mappings/aws/websites.mdx b/docs/providers/mappings/aws/websites.mdx index 90ac7e7f4..a7e32544c 100644 --- a/docs/providers/mappings/aws/websites.mdx +++ b/docs/providers/mappings/aws/websites.mdx @@ -20,5 +20,5 @@ The following resources are created when deploying Websites to AWS: 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 +- A CloudFront distribution is created to serve your website and rewrite all APIs to `/api/{apiName}` and websocket routes to `/ws/{websocketName}` using CloudFront Functions - Cache invalidation is automatic based on changed files diff --git a/docs/websites.mdx b/docs/websites.mdx index 5919cfd12..b861db818 100644 --- a/docs/websites.mdx +++ b/docs/websites.mdx @@ -159,12 +159,15 @@ However, client-side routes (like React Router) are not detected at deployment t The following paths are reserved for use by the Nitric framework and cannot be used as website paths: - `/api` - used to rewrite API requests +- `/ws` - used to rewrite websocket requests We are looking at making the **rewrite path configurable** in the future, so you will have more flexibility in defining your own path structure. -## API Routes +## API and Websocket Routes -If you have at least **one website enabled**, Nitric automatically serves your API under the `/api` path. +When you have at least **one website enabled**, Nitric automatically serves your API under the `/api` path and websocket routes under the `/ws` path. + +### Accessing Routes You can access your API routes at: @@ -172,24 +175,42 @@ You can access your API routes at: https:///api// ``` -### When Are API Routes Enabled? +And connect to websocket routes at: + +```bash +https:///ws/ +``` + +### When Are Routes Enabled? -API route rewrites are **only enabled if you have at least one website defined** in your project. -We are exploring options to allow enabling API routing **without requiring a website** in the future. +Both API and websocket route rewrites are **only enabled if you have at least one website defined** in your project. +We are exploring options to allow enabling these routes **without requiring a website** in the future. ### Why This Approach? -By serving your API under the same domain as your website, you avoid **CORS issues** and can use **relative paths** to access your API directly from your frontend code. +By serving your API and websocket routes under the same domain as your website, you avoid **CORS issues** and can use **relative paths** to access your routes directly from your frontend code. -### Example API Call +### Example Usage + +Here's how to use both API and websocket routes in your frontend code: ```javascript +// API Example 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) } + +// Websocket Example with a websocket named `chat` +const ws = new WebSocket('/ws/chat') + +ws.onmessage = (event) => { + console.log(event.data) +} + +ws.send('Hello, server!') ``` ## Support for Frameworks like Next.js