sailfork / t3code-github / .repos/ alchemy-effect/ website/ src/ content/ docs/ fly/ frontend/ nextjs.mdx

import PackageManagers from "../../../../components/PackageManagers.astro";
export const devDeps = "@alchemy.run/frontend-frameworks";

Fly.Website.Nextjs deploys a Next.js app to Fly as a long-running Node process. It runs a real next build, then a serve entry that import("next") + next({ dev: false }).prepare() + getRequestHandler() on port 3000:

  • one Fly.App (created if app is omitted) and a Fly.Service running Node on a Machine
  • a shared IPv4 so https://{app}.fly.dev answers
  • .next and public/ baked into the image; next, react, and react-dom installed unbundled

This is not OpenNext — those wrappers target Lambda and workerd. ISR and next/image use Next's own Node behavior.

App Router and Pages Router both work — server components, API routes, middleware, server actions, dynamic segments, streaming SSR, and getServerSideProps pages all run in the Node process.

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:

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

Declare the site as a module-level const (rather than inline in the Stack):

// alchemy.run.ts
import * as Fly from "@alchemy.run/fly";

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

Add it to the Stack

Yield the site from your Stack and return its URL:

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

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

url is https://{app}.fly.dev on deploy. app, service, ip, and certificate are set then and undefined under alchemy dev.

Pass an existing App to share it with other Services:

export const Website = Fly.Website.Nextjs("Website", { app: Site });

Add environment variables

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

// alchemy.run.ts
export const Website = Fly.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 Machine at deploy, so server code and NEXT_PUBLIC_* inlining see the same map in both modes.

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

bun alchemy dev

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

Custom domain

const site = yield* Fly.Website.Nextjs("Web", {
  domain: "app.example.com",
});

Alchemy requests an ACME Fly.Certificate on the App and url becomes https://app.example.com. Point DNS at the App first — v1 does not create DNS records.

Where next