cdk-nextjs 0.6.1 → 0.7.0

package/docs/init-cache-deployment.md

@@ -14,9 +14,16 @@ Pre-deployment of Next.js build cache files to S3 has been successfully implemen
 ### Deployment Time
 
 1. The `NextjsCache` construct checks for the `.next/cdk-nextjs-init-cache` directory
-2. If found, it uses `BucketDeployment` with a `{buildId}/` prefix to upload all pre-built cache files to S3
+2. If found, it copies the directory into a staging directory _under_ a `{buildId}/` directory and hands that to `BucketDeployment`
 3. Files are deployed to S3 with the path structure: `{buildId}/{cacheKey}.json`
 
+The build ID is in the staged paths rather than in `destinationKeyPrefix` on
+purpose: `BucketDeployment` tags its destination bucket with
+`aws-cdk:cr-owned:<destinationKeyPrefix>:<hash>`, and an `AWS::S3::Bucket`'s `Tags`
+are not hotswappable, so a prefix that changes per build forced a full
+CloudFormation deployment every time. See the comment on `createStagingDirectory`
+in `src/nextjs-cache.ts`.
+
 ### Runtime
 
 1. Lambda/containers have the cache handler configured with S3/DynamoDB credentials
@@ -50,6 +57,30 @@ Pre-deployment of Next.js build cache files to S3 has been successfully implemen
 - Timestamps for revalidation checking
 - Proper JSON serialization with special handling for Map/Buffer
 
+## Sizing
+
+`BucketDeployment`'s Lambda downloads the asset zip into `/tmp` and extracts it
+beside itself, so it needs room for both at once — and CDK gives it 512 MiB of
+ephemeral storage and 128 MB of memory by default. An app with many large
+prerenders blows through that: 60 pages carrying ~1 MB of RSC each produce a
+664 MiB seed directory, and the handler dies with
+`OSError: [Errno 28] No space left on device`. Under `cdk deploy --hotswap` that
+failure is invisible, because the CLI invokes custom resources with placeholder
+response URLs and never reads the status they send — the app comes up serving a
+partially seeded cache.
+
+`NextjsCache` therefore sizes that Lambda from the seed directory: twice its size
+plus headroom, floored at CDK's 512 MiB and capped at Lambda's 10 GiB, with
+`memoryLimit: 1024` past 256 MiB. Above the 10 GiB ceiling it warns; pass
+`overrides.bucketDeploymentProps` with `useEfs: true` for a cache that large.
+
+Cache entries themselves serialize Buffers as base64 (`serializeCacheValue` in
+`src/adapter/cache-utils.ts`). That matters for size _and_ for read latency:
+the integer-array format `Buffer.toJSON()` produces is ~3 bytes of JSON per byte
+of payload and makes `JSON.parse`'s reviver run once per element, which cost 4.8s
+of Lambda time to answer a single 1 MiB segment prefetch before it was changed.
+Both integer-array spellings are still accepted on read.
+
 ## Implementation Details
 
 ### Modified Files

package/docs/next-build-output-guide.md

@@ -1,38 +1,48 @@
 # Next.js Output Guide
 
-When a Next.js app is built with `next build` with standalone mode, here is a simplified version of it's output:
+cdk-nextjs registers a [Deployment Adapter](https://nextjs.org/docs/app/api-reference/adapters), and its `onBuildComplete` hook stages what gets deployed. Here is a simplified version of a build's output:
 
 - public ([Public Folder](https://nextjs.org/docs/app/api-reference/file-conventions/public-folder))
 - .next
-  - standalone
-    - relative/path/to/package
-      - .next
-        - server
-          - app ([Full Route Cache](https://nextjs.org/docs/app/deep-dive/caching#full-route-cache))
-            - api
-              - health
-                - route.js
-              - health.body
-              - health.meta
-            - my-dynamic-page
-              - page.js
-            - my-static-page
-              - page.js
-            - my-static-page.html
-            - my-static-page.meta
-            - my-static-page.rsc
+  - cdk-nextjs-adapter — the staged deployment root(s), one per function group
+    - manifest.json — routes, entrypoints and config the runtime dispatches from
+    - app — `app` when not splitting, otherwise one directory per group
+      - cdk-nextjs-runtime
+        - lambda.mjs (or server.mjs, for the Containers types) — the entrypoint
+        - manifest.json
+      - relative/path/to/package
+        - .next
+          - required-server-files.json, \*-manifest.json, BUILD_ID
+          - server
+            - app ([Full Route Cache](https://nextjs.org/docs/app/deep-dive/caching#full-route-cache))
+              - api
+                - health
+                  - route.js
+                - health.body
+                - health.meta
+              - my-dynamic-page
+                - page.js
+              - my-static-page
+                - page.js
+              - my-static-page.html
+              - my-static-page.meta
+              - my-static-page.rsc
+      - node_modules — only the files the routes in this group trace to
+  - cdk-nextjs-init-cache — prerendered pages as cache entries, keyed by route
   - static ([Static Assets](https://nextjs.org/docs/app/guides/self-hosting#static-assets))
 
 Notes:
 
-- [Standalone Output](https://nextjs.org/docs/pages/api-reference/config/next-config-js/output#automatically-copying-traced-files) copies only the necessary files for a production deployment including select files in node_modules which is ideal for keeping compute container image small. However, `next build` does not automatically copy the public and static folders into the standalone directory so that needs to be done.
+- The staged tree is keyed by path relative to the repo root, so in a monorepo the app sits at its own relative path inside the deployment root rather than at the top. `manifest.json` records that path.
+- `output: "standalone"` is **not** used. Standalone and the adapter are alternatives rather than layers: both close over the same [Node File Trace](https://nextjs.org/docs/pages/api-reference/config/next-config-js/output#automatically-copying-traced-files) results, so staging from the adapter hook produces the same closure while also letting cdk-nextjs split it per function group and add the runtime entrypoint.
+- `public` and `.next/static` are deliberately **not** in the deployment root: they are in S3, and a second copy of them can push a Lambda past the 250 MB unzipped cap on its own. `NextjsRegionalContainers` is the exception — it has no CDN in front of it, so its Dockerfile copies both into the image and its own server answers those requests.
 - .body, .meta, .html, and .rsc files are updated by Next.js as a part of [ISR](https://nextjs.org/docs/app/guides/incremental-static-regeneration)
 
 We could ship this off to Lambda/Fargate and call it a day, but then we wouldn't have a content delivery network serving our static assets nor a shared cache between compute containers. We use S3/CloudFront for serving static assets and S3/DDB for shared cache between compute containers.
 
 ## S3
 
-.next/static is simply copied to S3 and then CloudFront is configured to forward requests with paths match `\_next/static` or any paths in `public` folder to S3. `NextjsAssetsDeployment` is responsible for this. We also add S3 User Metadata with `BUILD_ID` to track which static files are apart of which deployment so we can prune later.
+.next/static is simply copied to S3 and then CloudFront is configured to forward requests with paths match `\_next/static` or any paths in `public` folder to S3. `NextjsStaticAssets` is responsible for this. We also add S3 User Metadata with `BUILD_ID` to track which static files are apart of which deployment so we can prune later.
 
 Note, with `NextjsRegionalContainers`, we unfortunately cannot configure ALB to forward static requests directly to S3 because the host header dictates which bucket you can route requests to and it's not reliable to manually name buckets based on your domain. Therefore, static assets are copied into the container image to be served in ECS Fargate.
 

package/examples/README.md

@@ -12,4 +12,8 @@ Example Next.js app based on [App Playground](https://app-router.vercel.app/) wi
 
 # Notes on app-playground
 
-The app-playground app comes from https://github.com/vercel/app-playground. In order to incorporate upstream changes, follow instructions [here](https://stackoverflow.com/a/24816134/9658768). Don't want to use git submodule because we need to make some modifications to code like add `output: 'standalone'` and including in pnpm monorepo.
+The app-playground app comes from https://github.com/vercel/app-playground. In order to incorporate upstream changes, follow instructions [here](https://stackoverflow.com/a/24816134/9658768). Don't want to use git submodule because we need to make some modifications to code like registering cdk-nextjs's adapter via `adapterPath` and including in pnpm monorepo.
+
+# Notes on bench-app
+
+`bench-app` is the app the [load tests](./load-tests) deploy. Unlike app-playground it calls nothing outside its own stack, so the load tests measure cdk-nextjs rather than a third-party API. Keep it that way when changing it.