# How to deploy a Next.js application

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

## 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

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

## How to do it

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. **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. **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. **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
   ```

## What this supports

- 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

## 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.
