Deploy Next.js

Leash detects Next.js automatically from your package.json. Before deploying, it runs a preflight build locally to catch errors early.

Auto-Detection

If your project has a package.json with a next dependency or a next.config.* file, Leash automatically selects the Next.js build strategy.

Terminal

$ cd my-nextjs-app

$ leash deploy

✓ Detected Next.js 15

✓ Preflight build passed

✓ Image built and pushed

✓ Deployed successfully!

→ https://my-nextjs-app-your-org.un.leash.build

Preflight Build

Leash runs npm run build locally before uploading your code. This catches errors fast and saves time.

What the preflight checks

Runs npm run build locally
Catches type errors before remote build
Validates that the build output is correct

Required: bind your server to $PORT

Leash deploys your app to Cloud Run, which injects an environment variable PORT (always 8080) into every container. Your start script must honor it. The default starter and create-next-app templates do this correctly, but if you copy a script from elsewhere or write your own, make sure it reads $PORT.

{
  "scripts": {
    "start": "next start -p ${PORT:-3000}"
  }
}

The ${PORT:-3000} pattern uses the Cloud Run-injected port when deployed, and falls back to 3000 for local development.

If you hardcode the port

Cloud Run will fail the startup probe and the URL will return HTTP 503 forever. The dashboard will still show the deployment as “active” — Cloud Run only checks that something is listening on the right port, not that your app is healthy.

Common Issue: TypeScript Target

Build fails with syntax errors?

Your tsconfig.json may be targeting ES5, which causes issues with modern syntax. Update it to a modern version:

{
  "compilerOptions": {
    "target": "ES2017",
    "module": "esnext"
  }
}