Deploy a Next.js site to LeafCloud.

Requirements

Validated with Node v24.22.1, Next.js 16.4.2, React 19.3.0, React DOM 19.3.0, and npm. Static export requires output: "export" and images: { unoptimized: true } in next.config.ts.

Steps

1. Create a project with the official starter:

   npx create-next-app@latest app --ts --eslint --app --no-src-dir --use-npm --yes < /dev/null

   cd app

2. Update next.config.ts. The validated change adds these settings and removes the starter’s incompatible cacheComponents: true and partialPrefetching: true settings:

   const nextConfig: NextConfig = {
     output: "export",
     images: { unoptimized: true },
     cacheComponents: true,
     partialPrefetching: true,
   };

3. Build and preview the deployment:

   leaf deploy --dry-run

   Expected output from the validated run:

   Framework: Next.js
   Package manager: npm
   Build command: npm run build
   Output directory: out
   Files: 40
   Total size: 842034 bytes
   Dry run: nothing was uploaded.

   A real deploy prints ✓ Live at <url> (<files> files, <uploaded> uploaded) instead of the final dry-run line.

What LeafCloud detects

Next.js; npm run build; out.

Common problems

• Next.js must set output: 'export' to deploy as a static site — add output: "export" to next.config.ts.
• Next.js server features cannot be deployed as a static site: revalidate — remove the server feature, such as export const revalidate = 60;.
• Next.js server features cannot be deployed as a static site: next/image without images.unoptimized: true (<project>/app/page.tsx) — add images: { unoptimized: true } to next.config.ts.

For agents

Run leaf deploy --dry-run --json first. Check the exit code and stop if the JSON contains "error". After a successful dry run, run leaf deploy --json --yes. Never print credentials.

Validated on 2026-10-23 with Next.js 16.4.2.