AMPLE

NEXT.JS DEPLOYMENT

How to deploy a Next.js application

Deploy a Next.js application on a Node 22 runtime, including workspace projects and server-rendered routes.

By Ample ComputerUpdated July 30, 2026

DIRECT ANSWER

The short version

A Next.js application needs a Node-compatible production runtime unless it is exported as a fully static site. Ample detects the app, builds it in an isolated builder, selects a Node 22 server for a new runtime, starts the production output, and activates the route after health checks pass.

WHO THIS IS FOR

Before you start

This guide is for builders deploying a standalone Next.js app or a Next.js package inside a JavaScript workspace.

STEP BY STEP

How to do it

  1. 1

    Run the production build

    Use the repo's package manager and fix any build-time environment or type errors before deployment.

    npm run build
  2. 2

    Choose the correct deploy root

    Deploy a standalone app from its own directory. If it imports workspace packages through workspace dependencies, deploy from the workspace root so the lockfile and sibling packages are available.

  3. 3

    Plan the service

    For a workspace or multi-service repo, let Ample record the service path, root build context, runtime, and start command.

    ample plan --write
  4. 4

    Deploy and test server routes

    Apply the plan, open the generated URL, and test server-rendered pages, route handlers, and any linked services.

    ample up

FIT CHECK

What this supports

Good fit

  • Next.js server-rendered applications
  • Next.js projects using npm, pnpm, yarn, or bun
  • Workspace builds from the repository root
  • Build-time NEXT_PUBLIC_ environment variables

Know the limits

  • A Node app cannot run on a server image that lacks Node
  • Workspace packages are unavailable if only a dependent subdirectory is packaged
  • NEXT_PUBLIC_ values are shipped to browsers and cannot contain secrets

TROUBLESHOOTING

Common failure modes

The runtime reports node: not found

Deploy to a new runtime-matched server or another existing Node server.

A workspace dependency cannot be installed

Deploy from the workspace root and use a root build command that targets the Next.js service.

The build cannot access a required value

Pass the environment variable during deployment and keep secrets outside the public NEXT_PUBLIC_ namespace.

KEEP READING