feat: deploy / adapter / AWS Lambda

docs/src/pages/en/(pages)/deploy/aws.mdx

@@ -0,0 +1,288 @@
+---
+title: AWS
+category: Deploy
+order: 2
+---
+
+import Link from "../../../../components/Link.jsx";
+
+# AWS
+
+To deploy to AWS, use the `@lazarv/react-server-adapter-aws` package. This adapter is specifically designed to support the AWS cloud infrastructure and different tookits (AWS CDK, sst, serverless framework).
+
+<Link name="installation">
+### Installation
+</Link>
+
+Add the `@lazarv/react-server-adapter-aws` package to your project:
+
+```sh
+pnpm add -D @lazarv/react-server-adapter-aws
+```
+
+Add this to `.gitignore`:
+`.aws-react-server`
+
+Then you need to add the adapter to your `react-server.config.mjs` file:
+
+```mjs
+export default {
+  adapter: '@lazarv/react-server-adapter-aws',
+};
+```
+
+**Streaming** can be activated by setting the property `streaming: true`:
+```mjs
+export default {
+adapter: [ '@lazarv/react-server-adapter-aws', {streaming: true} ]
+};
+```
+> **Note:** check if your deployment toolkit (e.g. AWS CDK) supports streaming!
+
+AWS deployment toolkits:
+* [SST V3 (ion)](#sst-v3-ion)
+* [AWS CDK](#aws-cdk)
+* [Serverless Framework V3](#serverless-framework-v3)
+
+Each toolkit can optional support additional configuration properties:
+```mjs
+export default {
+  adapter: [ '@lazarv/react-server-adapter-aws', {streaming: true,
+    "toolkitDefault":"cdk",
+    "toolkit":{
+      "cdk": {
+        "stackName":"myStack"
+      },
+      "sst": {}
+    }
+  }]
+};
+```
+When multiple configuration exist the property `"toolkitDefault" : "cdk",` is required!
+
+<Link name="sst-v3-ion">
+## [SST V3 (ion)](https://sst.dev)
+</Link>
+
+### Architecture
+
+* AWS Cloudfront - globals CDN and reverse proxy for the framework and the static assets
+  - path `_server/` origin Lambda - no caching
+  - path `assets/` and `client/` are created by the framework, contain your assets and client code with a cache breaker filename - origin S3
+  - path any other root directory copied from `public` folder or created as a result of static pages - origin S3 (__CloudFront defaults to max. 10 behaviors which allow 8 additional root directories!__)
+  - any url not catched above - origin Lambda - no caching
+* AWS Lambda URL Function - provides the react-server framework
+* AWS S3 - static assets
+* Resources from S3 have a `cache-control: public,max-age=0,s-maxage=86400,stale-while-revalidate=86400` header
+
+> **Note:** Currently only deployment is supported, dev mode is not implemented.
+
+<Link name="installation-sst">
+### Installation
+</Link>
+
+1. First you need to initialize your project with sst. You can do this by running the following command:
+
+```sh
+pnpm add sst
+pnpm sst init
+```
+
+```
+>  JS project detected. This will...
+   - use the JS template
+   - create an sst.config.ts
+
+? Continue:
+```
+
+**Answers:** Yes
+
+```
+? Where do you want to deploy your app? You can change this later: 
+```
+
+**Answers:** aws
+
+2. Create the `sst-react-server.ts` sst stack to your project and add the stack to `sst.config.ts`:
+
+```sh
+pnpm build
+```
+
+**Optional manual `sst.config.ts` setup:**
+
+1. add `import { ReactServer } from "./sst-react-server";`
+2. replace `async run() {},`with:
+```mjs
+async run() {
+    new sst.aws.ReactServer("ReactServertackDemoApp");
+  },
+```
+
+<Link name="configuration-sst">
+## Configuration
+</Link>
+
+All possible configuration options are documented here:
+`./sst-react-server.ts`
+
+<Link name="deploy-sst">
+### Deploy
+</Link>
+
+You can build and deploy your application to AWS using the following command:
+
+```sh
+pnpm sst deploy
+```
+
+>  **Error:**
+> `TypeError: aws_exports.ReactServer is not a constructor`
+> 
+> run `pnpm build` again to fix missing ReactServer stack to sst.
+
+**remove stack:**
+```sh
+pnpm sst remove
+```
+
+<Link name="aws-cdk">
+## [AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html)
+</Link>
+
+> **Note:** Streaming is not supported.
+
+### Architecture
+* AWS Cloudfront - globals CDN and reverse proxy for the framework and the static assets
+* AWS API Gateway - used by AWS Lambda function
+* AWS Lambda Function - provides the react-server framework
+* AWS S3 Bucket - browser client code and static assets with cache breakers
+* AWS S3 Bucket - static assets from public folder and static pages
+
+Bei default, all static routes to existing files are uploaded to a Cloudfront KV store and used to directly redirect requests to static items on edge to the s3 bucket.
+As there is a 5MB Limit on the KV store size and only 512Byte for the keys (max. length of url) you can use the property `staticRoutes` to define a list of root directories which are directly handled by cloudfront without the need a lookup in the KV store.
+
+<Link name="installation-cdk">
+### Installation
+</Link>
+
+First you need to install this packages:
+
+```sh
+pnpm add aws-cdk-lib constructs source-map-support
+pnpm add -D aws-cdk tsx
+```
+
+add to `.gitignore`: 
+
+```.gitignore
+cdk.out
+```
+
+Third, add the `ReactServer()` cdk stack `cdk/lib/react-server-stack.ts`:
+
+```sh
+touch cdk.json
+pnpm build
+```
+> **Note:** will only add a sample configuration when `cdk.json` is empty.
+
+Optional properties of the stack `react-server.config`:
+```json
+{
+"adapter": [
+    "@lazarv/react-server-adapter-aws",
+    {
+      "streaming": false,
+      "toolkit": {"cdk":{
+        "stackName": "ReactStackStack-001", 
+        "cdkFolderPath": "cdk", // default: './cdk'
+        "stackProps": {
+          "description": "Hello World Stack"
+          "domainName": "example.com",
+          "subDomain": "www",
+          "certificate": "arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012" //or a certificatemanager.ICertificate
+          "hostedZone": route53.HostedZone.fromLookup(stack, "MyHostedZone", { domainName: "example.com" })
+          "staticRoutes": ["/assets/","/client/"], // (optional) this catch all routes are created as caching behaviors on cloudfront and point to the static assets on S3. Alle Routes need to start with a "/"! 
+          "maxBehaviors": 10, // (optional) defaults to the AWS limit for Cloudfront behaviors
+          env: {
+            account: '123456789012',
+            region: 'us-east-1'
+          },
+        }
+      }}
+    }
+  ]
+}
+```
+
+<Link name="deploy-cdk">
+### Deploy
+</Link>
+
+Build the project and deploy with the command from the cdk toolkit.
+
+```sh
+pnpm build
+pnpm cdk deploy --all
+```
+
+**remove stack:**
+
+```sh
+pnpm cdk destroy --all
+```
+
+<Link name="serverless-framework-v3">
+## Serverless Framework V3
+</Link>
+
+> **Note:** Streaming is not supported and there are no plans to support Version 4.x.
+
+### Architecture
+* AWS Cloudfront - globals CDN and reverse proxy for the framework and the static assets
+* AWS API Gateway - used by AWS Lambda function
+* AWS Lambda Function - provides the react-server framework
+* AWS S3 - static assets
+
+add the following packages:
+```sh
+pnpm add -D serverless@3 serverless-cloudfront-invalidate serverless-s3-sync
+```
+
+add to `.gitignore`:
+
+```.gitignore
+.serverless
+```
+
+run this commands to create a sample configuration:
+
+```sh
+touch serverless.yml
+pnpm build
+```
+
+> **Note:** will only add a sample configuration when `serverless.yml` is empty.
+
+<Link name="deploy-sls">
+### Deploy
+</Link>
+
+Build the project and deploy with the command from the sls toolkit.
+
+```sh
+pnpm build
+pnpm sls deploy
+```
+
+get FrontendCloudFrontDistributionUrl:
+`pnpm sls info --verbose`
+
+Configuration of the stack is possible in `serverless.yml`.
+
+**remove stack:**
+```sh
+pnpm sls remove
+```

examples/hello-world-aws/.gitignore

@@ -0,0 +1,14 @@
+# react-server adapter aws
+.aws-react-server
+# aws-cdk
+.cdk.staging
+cdk.out
+# serverless framework
+.serverless
+# sst
+bundle/*
+# this files are generated by sst and should be checked in!
+.sst
+sst-react-server.ts
+sst-env.d.ts
+sst.config.ts

examples/hello-world-aws/README.md

@@ -0,0 +1,14 @@
+# Deploy Adapter AWS
+
+AWS adapter for [@lazarv/react-server](https://npmjs.com/package/@lazarv/react-server).
+
+The bundling of the app for deployment to AWS Lambda requires the aws adapter in `react-server.config.json`:
+
+```json
+{
+  "root": "src",
+  "adapter": "@lazarv/react-server-adapter-aws"
+}
+```
+
+See details at https://react-server.dev/deploy/aws.

examples/hello-world-aws/cdk.json

@@ -0,0 +1,4 @@
+{
+  "app": "tsx cdk/bin/infrastructure.ts",
+  "context": {}
+}

examples/hello-world-aws/cdk/.gitignore

@@ -0,0 +1 @@
+stack.config.ts