## The short version

Move a Next.js app's compute from Vercel to Ample. Server-rendered apps run with next build and next start; static exports are published as static sites; environment variables move with --env; a PostgreSQL database can be supplied by URL or auto-provisioned. Cutover is a DNS change with ample domain, and Vercel stays untouched until you confirm.

## What it needs

- [Compute](/content/discover/primitive/compute/index.html): verified (Apps run in isolated x86_64 Firecracker microVMs; sizes are the priced VM sizes.)
- [Postgres](/content/discover/primitive/postgres/index.html): verified (Managed PostgreSQL 16 runs in its own microVM and is auto-provisioned when an app needs a database and no DATABASE_URL is supplied.)

## Before you start

- The Next.js source and its environment variable names and values
- next start bound to 0.0.0.0 on PORT (Vercel does not require this; Ample does)
- A component inventory: edge middleware, ISR, image optimization, cron and Vercel-specific integrations are not migrated by this recipe
- An Ample account token with servers:write, databases:read and domains:write for cutover

## How to do it

1.  **Inventory**

List what the app uses on Vercel. Compute and environment variables are in scope; edge middleware, ISR revalidation, image optimization, cron jobs and Vercel integrations are out of scope and must be reviewed.

2.  **Deploy to Ample in parallel**

Deploy the same source with its environment variables; Vercel keeps serving production.
    
    ```
    ample deploy . --name <app-name> --public --env KEY=value
    ```

3.  **Validate on the Ample URL**

Run the app's smoke tests and the success checks; compare responses with production.

4.  **Cut over DNS**

Add the custom domain and set the documented DNS records; TLS is issued automatically. Keep Vercel until traffic is verified.
    
    ```
    ample domain add <domain> --app <app-name>
    ```

5.  **Rollback**

Point DNS back to Vercel. Nothing on Vercel was changed by this recipe.

## Examples

- **Static export canary** (`tests/deploy-canaries/next-static-export`): Vercel-style static export served with correct 404 handling.
- **SSR canary** (`tests/deploy-canaries/next-basic-ssr`): next build and next start.
- **Next.js + pg canary** (`tests/deploy-canaries/next-postgres-basic`): Database connection from a route handler with an auto-provisioned managed database.

## How to know it worked

- page renders on the Ample URL (`/` on the live URL, expect ample canary next basic ssr)
- database route reports a live connection (`/api/db` on the live URL, expect postgres=ok)

## Cost estimate

Estimated 10.00 USD per month (size prices from pricing.toml at build revision ca0b484a7a9957c573a88d3a32dc603c3c10135a).

- app server x1 `s-1vcpu-1gb`: 5.00 USD
- managed PostgreSQL database x1 `s-1vcpu-1gb`: 5.00 USD

Upper-bound monthly price of the tested sizes. Plan quotas and budgets apply.

## Verification evidence

- canary_run on 2026-09-19T23:55:33Z at revision `1764076-tls-account-903d345`: Next.js static export (Vercel-style output) was published and served, including a nested route and a correct 404. (expires 2027-03-18T23:55:33Z)
- canary_run on 2026-09-19T23:55:33Z at revision `1764076-tls-account-903d345`: Next.js 15 SSR app (next build, next start) deployed on node-22; the page and an API route served correctly. (expires 2027-03-18T23:55:33Z)
- canary_run on 2026-09-20T01:42:25Z at revision `199ff1dfd52683832ae75d3f98b53a7a4bff7f96 (CLI e3181f5)`: Next.js 15 route handler using pg with no DATABASE_URL supplied: Ample auto-provisioned a managed PostgreSQL database and /api/db reported postgres=ok. (expires 2027-03-19T01:42:25Z)

## Execution binding

No execution binding. This recipe is documentation only; nothing is executed automatically.

## Typed next actions

- Browse the catalog index (`GET /v1/catalog` on the api origin; authentication not required, approval not required)
- Search published recipes by intent, stack and constraints (`POST /v1/catalog/search` on the api origin; authentication not required, approval not required)
- Prepare a side-effect-free deployment plan for an authorized project (`POST /v1/catalog/plan` on the api origin; authentication required, approval not required)
- Read the existing agent authentication setup (`GET /mcp/setup` on the api origin; authentication not required, approval not required)
- Browse Vercel app (`GET /v1/catalog/nodes/migration%3Avercel-app` on the api origin; authentication not required, approval not required)
- Browse Next.js (`GET /v1/catalog/nodes/stack%3Aframework-next-js` on the api origin; authentication not required, approval not required)
- Browse Migrate compute (`GET /v1/catalog/nodes/intent%3Amigrate-compute` on the api origin; authentication not required, approval not required)

## Identifiers and status

Recipe `page:migrate:vercel-app:next-js`. Revision r1.

release **published** support **verified** execution **unbound**

Formats: [HTML](/content/migrate/vercel-app/next-js/index.html) \| [Markdown](/content/migrate/vercel-app/next-js.md) \| [JSON contract](https://api.ample.computer/v1/catalog/recipes/page%3Amigrate%3Avercel-app%3Anext-js)