Configure build and start for Next.js

Summary

Configure build and start for a Next.js app on Ample. A server-rendered app runs next build then next start on the node-22 template with the detected package manager; a static export is published as a static site. The app must bind 0.0.0.0 on PORT.

Infrastructure requirements

• Compute: verified (Apps run in isolated x86_64 Firecracker microVMs that auto-pause when idle and wake on request; sizes are the priced VM sizes.)

Prerequisites

• A package.json with build and start scripts (next build, next start -H 0.0.0.0 -p ${PORT:-3000})
• Node 22 compatible dependencies
• An Ample account token with servers:write

Exact tested configuration

• template: node-22
• runtime: node
• size: s-1vcpu-1gb
• install: npm install
• build: npm run build --if-present
• start: npm run start

Steps

1. Make next start listen correctly. Use next start -H 0.0.0.0 -p ${PORT:-3000} so the health check reaches the server.
2. Deploy. Run the existing synchronous deploy once from the project directory and read the result. Exit 0 is live, 1 is failed, 2 is blocked on a required preflight action. Re-running with no change is a content-addressed no-op.

   ample deploy . --name <app-name> --public --format json

3. Static exports. With output: 'export' the build is published as a static site with correct 404 handling; no server process runs.
4. Verify. Fetch the live URL and run the success checks below. On failure read the build log, then the runtime log, fix the cause and deploy again; do not blind-retry.

   ample logs <deployment_id> --kind build

Tested examples

• Next.js SSR canary (tests/deploy-canaries/next-basic-ssr): next build and next start with a page and an API route.
• pnpm Next.js canary (tests/deploy-canaries/pnpm-next-basic): Package manager detection with pnpm.
• Static export canary (tests/deploy-canaries/next-static-export): output: 'export' published as a static site.

Success checks

• page renders (/ on the live URL, expect ample canary next basic ssr)
• API route stays a Next route (/api/canary on the live URL, expect next api stays next)

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.
• Next.js 15 was tested; other majors are not verified.
• Image optimization, ISR and middleware behavior are not verified.

Cost estimate

Estimated 5.00 USD per month (size prices from pricing.toml at build revision a1b8c38919e59cd035ebabaced73cf84ece24371).

• app server x1 s-1vcpu-1gb: 5.00 USD

Apps and managed databases auto-pause when idle; the estimate is the always-on 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 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-19T23:55:33Z at revision 1764076-tls-account-903d345: Next.js app using pnpm deployed with the detected package manager. (expires 2027-03-18T23:55:33Z)
• 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)

Last verified: 2026-09-19T23:55:33Z

Execution binding

MCP tool ample_deploy (registry mcp:ample_deploy), schema hash 876465fce906da0c observed 2026-09-20T01:55:48.667900+00:00 at revision 199ff1dfd526, binding state current, required scopes: servers:write.