# Migrate Vercel app: Next.js

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.

## Representative Queries
- Migrate Vercel app: Next.js
- Where can I host Next.js built with Next.js?
- I need a component-scoped export/import or reconfiguration procedure for Next.js, with compatibility checks, verification and rollback.

## Resource Requirements
- primitive:compute
- primitive:postgres

## Infrastructure Requirements
- **Compute**: Apps run in isolated x86_64 Firecracker microVMs that auto-pause when idle and wake on request; sizes are the priced VM sizes.
- **Postgres**: Managed PostgreSQL 16 runs in its own microVM and is auto-provisioned when an app needs a database and no DATABASE_URL is supplied.

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

## Workflow Steps
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.
   ```bash
   ample deploy . --name <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.
   ```bash
   ample domain add <domain> --app <app>
   ```
5. **Rollback**: Point DNS back to Vercel. Nothing on Vercel was changed by this recipe.

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

## Success Checks
- Page renders on the Ample URL
  - Kind: http_get
  - Path: `/`
  - Expect: `ample canary next basic ssr`
- Database route reports a live connection
  - Kind: http_get
  - Path: `/api/db`
  - Expect: `postgres=ok`

## Limitations
- Verified on the node-22 template at s-1vcpu-1gb; other templates and sizes are not verified by this recipe.
- Region, compliance attestations and request-duration limits are unknown and not claimed.
- Apps auto-pause when idle and wake on the next request; always-on is an operator setting, not a plan feature.
- Documentation only: the catalog does not execute the migration; each stage is a normal authenticated deploy or domain command.

## Cost Estimate
- **Monthly Amount**: 10.00 USD
- Detail Basis: Size prices from pricing.toml (loaded by the API) at build revision 1ac5595375130d45290090e82ed0f554ccd45405-dirty
- Components:
  - Name: App server, Size: s-1vcpu-1gb, Quantity: 1.0, Monthly Amount: 5.0 USD
  - Name: Managed PostgreSQL database, Size: s-1vcpu-1gb, Quantity: 1.0, Monthly Amount: 5.0 USD

## Evidence Summary
- **Static export**: Next.js static export (Vercel-style output) was published and served, including a nested route and a correct 404.
  - Observed At: 2026-09-19T23:55:33Z
- **SSR app**: Next.js 15 SSR app (next build, next start) deployed on node-22; the page and an API route served correctly.
  - Observed At: 2026-09-19T23:55:33Z
- **Database connection**: 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.
  - Observed At: 2026-09-20T01:42:25Z

## Next Actions
- Browse the catalog index.
- Search published recipes by intent, stack and constraints.
- Prepare a side-effect-free deployment plan for an authorized project.
- Read the existing agent authentication setup.
- Browse Vercel app.
- Browse Next.js.
- Browse Migrate compute.