Skip to content

Next.js

Archil.Website.Nextjs deploys a Next.js app to an Archil sandbox, as a long-running Node process (next build, then next({ dev: false })); next, react and react-dom are installed next to it with npm install. The site is the program of its own sandbox, on port 3000, at a public https://3000-…archil.app URL. A stopped sandbox starts again on the next request.

Install

Section titled “Install”

The build integration is not bundled with alchemy. Install @alchemy.run/frontend-frameworks; the resource loads the package’s /nextjs/node export from your project at deploy time. It is only used at build time, so a dev dependency is enough. Your app still needs next, react, and react-dom as usual:

Terminal window
pnpm add -D https://pkg.alchemy.run/@alchemy.run/frontend-frameworks/pr:2930:0cabab6

Configure Next.js

Section titled “Configure Next.js”

Your next.config.* is loaded and honored as-is — the build runs a real next build, and Alchemy never rewrites the file. There is no adapter to install and no open-next.config.ts to write.

Pass rootDir when the Next.js project is not the stack root.

Declare the Website

Section titled “Declare the Website”

Declare the site as a module-level const:

alchemy.run.ts
import * as Archil from "@alchemy.run/archil";


export const Website = Archil.Website.Nextjs("Website");

sandbox sizes the site’s sandbox and sets its image, timeouts, disks and network policy:

alchemy.run.ts
export const Website = Archil.Website.Nextjs("Website", {
  sandbox: { vcpuCount: 2, memSizeMiB: 4096, idleTtlSeconds: 600 },
});

Add it to the Stack

Section titled “Add it to the Stack”

Yield the site from your Stack and return its URL:

alchemy.run.ts
import * as Archil from "@alchemy.run/archil";
import * as Alchemy from "alchemy";
import * as Effect from "effect/Effect";


export const Website = Archil.Website.Nextjs("Website");


export default Alchemy.Stack(
  "MyNextjsSite",
  {
    providers: Archil.providers(),
    state: Alchemy.localState(),
  },
  Effect.gen(function* () {
    const site = yield* Website;
    return { url: site.url };
  }),
);

Run alchemy deploy. url is the site’s https://3000-…archil.app URL. site.sandbox is the sandbox behind it, and undefined under alchemy dev.

See examples/archil-website-nextjs for the checked-in example.

Add environment variables

Section titled “Add environment variables”

Process environment is the top-level env prop — plain strings, or Redacted secrets:

alchemy.run.ts
export const Website = Archil.Website.Nextjs("Website", {
  env: {
    GREETING: "Hello from Alchemy!",
    API_BASE: "https://api.example.com",
  },
});

The values are copied onto process.env before next build / next dev, and onto the program at deploy, so server code and NEXT_PUBLIC_* inlining see the same map in both modes.

Read the environment in server code

Section titled “Read the environment in server code”

The Next server is a plain Node process, so route handlers, server components, and server actions read the environment from process.env:

app/api/hello/route.ts
export function GET() {
  return Response.json({ greeting: process.env.GREETING ?? "hello" });
}

Local dev

Section titled “Local dev”
Terminal window
bun alchemy dev

alchemy dev runs next dev (native HMR, Turbopack) instead of deploying; site.url is the local address and no Archil resources are created. Wrap the site in Alchemy.remote() to deploy the live sandbox even during dev.

Where next

Section titled “Where next”