@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
mdx 176 lines 5.23 KB
Raw
1 ---
2 title: Next.js
3 description: Deploy a Next.js app to AWS with AWS.Website.Nextjs — Next's own server on a Lambda Web Function with a shared S3 cache, S3 assets behind CloudFront, and next dev under alchemy dev.
4 sidebar:
5 order: 9
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 export const devDeps = "@alchemy.run/frontend-frameworks";
11
12 `AWS.Website.Nextjs` deploys a [Next.js](https://nextjs.org) app to
13 AWS. Next runs as its own standalone server on a
14 [Lambda Web Function](/aws/compute/web-functions), the way it runs under
15 `next start`: each environment serves many requests, responses stream, and
16 ISR revalidation and `/_next/image` happen in the server. Static assets are
17 served from S3 through CloudFront's edge router, and an S3 bucket holds the
18 cache every environment shares.
19
20 App Router and Pages Router both work — server components, API
21 routes, middleware, server actions, dynamic segments, streaming SSR,
22 and `getServerSideProps` pages all run on the server.
23
24 ## Install
25
26 The build integration is not bundled with alchemy. Install
27 `@alchemy.run/frontend-frameworks`; the resource loads the package's
28 `/nextjs/aws` export from your project at deploy time. It is only used at
29 build time, so a dev dependency is enough:
30
31 <PackageManagers dev={devDeps} />
32
33 ## Configure Next.js
34
35 Your `next.config.*` is loaded and honored as-is: the build runs a real
36 `next build`, and Alchemy never rewrites the file. It builds Next's
37 standalone output for you, so there's no `output` to set; an `output`
38 other than `"standalone"` fails the build.
39
40 ## Declare the Website
41
42 Declare the site as a module-level const (rather than inline in the
43 Stack):
44
45 ```typescript
46 // alchemy.run.ts
47 import * as AWS from "@alchemy.run/aws";
48
49 export const Website = AWS.Website.Nextjs("Website");
50 ```
51
52 ## Add it to the Stack
53
54 Yield the site from your Stack and return its URL:
55
56 ```typescript
57 // alchemy.run.ts
58 import * as Alchemy from "alchemy";
59 import * as Effect from "effect/Effect";
60
61 export default Alchemy.Stack(
62 "MyNextjsSite",
63 {
64 providers: AWS.providers(),
65 state: AWS.state(),
66 },
67 Effect.gen(function* () {
68 const site = yield* Website;
69 return { url: site.url };
70 }),
71 );
72 ```
73
74 Statically-rendered pages are served from the S3 prerender cache;
75 dynamic pages and route handlers stream from the server;
76 `next/image` requests are handled by the dedicated optimizer.
77
78 See
79 [examples/aws-website-nextjs](https://github.com/alchemy-run/alchemy/tree/main/examples/aws-website-nextjs)
80 for the checked-in example.
81
82 ## Add environment variables
83
84 The server function's environment is configured under `env` — plain
85 values, or outputs from other resources in the Stack:
86
87 ```diff lang="typescript"
88 // alchemy.run.ts
89 export const Website = AWS.Website.Nextjs("Website", {
90 + env: {
91 + GREETING: "Hello from Alchemy!",
92 + API_BASE: api.url,
93 + },
94 });
95 ```
96
97 The values are set on the server at deploy time and injected
98 into the dev server's process environment under `alchemy dev`, so
99 server code reads the same values in both modes.
100
101 ## Read the environment in server code
102
103 Next's server is a plain Node server, so route handlers,
104 server components, and server actions read the environment from
105 `process.env`:
106
107 ```typescript
108 // app/api/hello/route.ts
109 export function GET() {
110 return Response.json({ greeting: process.env.GREETING ?? "hello" });
111 }
112 ```
113
114 ## ISR
115
116 Incremental Static Regeneration works out of the box. Alchemy configures
117 Next with an S3 `cacheHandler`, so ISR pages, route handlers, the fetch
118 cache and optimized images live in one bucket that every environment
119 shares. `revalidatePath` and `revalidateTag` in one environment reach all
120 of them, and time-based `revalidate` windows regenerate pages in the
121 background, in the server, as they do under `next start`.
122
123 ```typescript
124 // app/api/revalidate/route.ts
125 import { revalidatePath } from "next/cache";
126
127 export async function POST() {
128 revalidatePath("/blog");
129 return Response.json({ revalidated: true });
130 }
131 ```
132
133 `"use cache"` entries stay in each environment's memory.
134
135 ## Run on a Lambda Function
136
137 For servers that need more than 2 GB of memory or x86_64, or Regions
138 without Web Functions, set `server: "function"`. The app then builds with
139 [OpenNext](https://opennext.js.org/aws): the server and the image optimizer
140 run on Lambda Functions behind Function URLs, and ISR revalidation runs
141 through an SQS queue, a consumer Lambda and a DynamoDB tag table. Install
142 `@opennextjs/aws` as a dev dependency, and tune the server with
143 `memorySize`, `architecture`, and `runtime`:
144
145 ```diff lang="typescript"
146 // alchemy.run.ts
147 export const Website = AWS.Website.Nextjs("Website", {
148 + server: "function",
149 + memorySize: 2048,
150 });
151 ```
152
153 An `open-next.config.ts` is optional; without one Alchemy generates a
154 default with the `aws-lambda-streaming` wrapper.
155
156 ## Local dev
157
158 ```sh
159 bun alchemy dev
160 ```
161
162 `alchemy dev` runs `next dev` (native HMR, Turbopack) instead of
163 deploying; `site.url` is the local address and no AWS resources are
164 created. Wrap the site in `Alchemy.remote()` to deploy the real
165 infrastructure even during dev.
166
167 ## Custom domain
168
169 ```typescript
170 const site = yield* AWS.Website.Nextjs("Web", {
171 domain: { name: "app.example.com" },
172 });
173 ```
174
175 The hosted zone is inferred from the hostname. Pass `hostedZoneId` to
176 pin it when several zones could match.