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

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

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