Deploy a Next.js App Step by Step (From create-next-app to a Live Custom Domain)

This guide walks through deploying a Next.js app from scratch: scaffold the project, configure the build output, set environment variables, deploy to production, and add a custom domain with automatic SSL.

Step 1: Create a Next.js app

Scaffold a new Next.js project:

npx create-next-app@latest my-nextjs-app
cd my-nextjs-app

When prompted, choose the App Router and TypeScript (or JavaScript, depending on your preference). The CLI generates a working Next.js app with a sample page.

Run it locally:

npm run dev

Open http://localhost:3000 to verify it works.

Step 2: Choose static export or server mode

Next.js can build two ways:

• Static export (output: 'export') — generates HTML files, served from a CDN with zero runtime cost
• Server mode (output: 'standalone') — bundles a Node.js server that handles SSR and API routes

For this walkthrough, we will deploy in server mode (standalone) to support server-side rendering.

Edit next.config.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone'
};

module.exports = nextConfig;

Build locally to verify:

npm run build

The output directory is .next/standalone/. This folder contains a self-contained Node.js server.

Step 3: Add a health check endpoint

The platform probes your app to verify it is ready to receive traffic. Add a health check endpoint:

// app/api/health/route.js (App Router)
export async function GET() {
  return Response.json({ status: 'healthy' });
}

Or for Pages Router:

// pages/api/health.js
export default function handler(req, res) {
  res.status(200).json({ status: 'healthy' });
}

Test it locally:

npm run dev
curl http://localhost:3000/api/health
# {"status":"healthy"}

Step 4: Create a pandastack.json config

In your repo root, add pandastack.json:

{
  "type": "container",
  "language": "nodejs",
  "healthCheckPath": "/api/health",
  "env": [
    { "name": "NODE_ENV", "description": "Node environment (production)" },
    { "name": "DATABASE_URL", "description": "PostgreSQL connection string (optional)" }
  ]
}

This tells PandaStack to deploy as a container, probe /api/health for readiness, and prompt for environment variables during deployment.

Commit and push to GitHub:

git add .
git commit -m "Add pandastack.json config"
git push origin main

Step 5: Deploy via the deploy button

Add a deploy button to your README.md:

[![Deploy to PandaStack](https://dashboard.pandastack.io/deploy-button.svg)](https://dashboard.pandastack.io/deploy?repo=yourorg/my-nextjs-app&type=container)

Click the button. PandaStack clones your repo, reads pandastack.json, and prompts for environment variables. Set NODE_ENV=production. If you have a managed PostgreSQL database, paste the connection string for DATABASE_URL. Otherwise, leave it blank.

The build starts immediately. Watch logs in the dashboard under the project → Logs tab. When the deployment completes, you get a live HTTPS URL like https://my-nextjs-app-abc123.pandastack.app.

Step 6: Set environment variables

If you skipped environment variables during the initial deploy, set them via the CLI:

npm install -g @pandastack/cli
panda login
panda projects env set my-nextjs-app NODE_ENV=production
panda projects env set my-nextjs-app DATABASE_URL=postgresql://user:pass@host/db

Changes to runtime variables take effect on the next deploy. Changes to NEXT_PUBLIC_* variables (build-time) require a rebuild.

Step 7: Add a custom domain

In the dashboard, navigate to Project Settings → Domains. Add your domain (e.g., www.yourdomain.com). PandaStack provides a CNAME target like my-nextjs-app.pandastack-dns.com.

Point your DNS:

www.yourdomain.com  CNAME  my-nextjs-app.pandastack-dns.com

DNS propagation takes 5–60 minutes. When it resolves, PandaStack provisions a Let's Encrypt TLS certificate automatically. HTTPS works within minutes.

Test the custom domain:

curl https://www.yourdomain.com/api/health
# {"status":"healthy"}

Step 8: Enable automatic deploys on push

In the dashboard, navigate to Project Settings → Git Integration. Enable "Auto-deploy on push to main". Every time you push to main, PandaStack rebuilds and redeploys automatically.

Or use the API to enable it:

curl -X PATCH https://api.pandastack.io/v1/projects/my-nextjs-app \
  -H "Authorization: Bearer $PANDASTACK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "autoDeploy": true }'

Step 9: Test zero-downtime redeploy

Make a change to your app (e.g., edit app/page.js to change the homepage text). Commit and push:

git add .
git commit -m "Update homepage text"
git push origin main

PandaStack detects the push, builds the new version, starts new pods, waits for health checks to pass, routes traffic to the new pods, and shuts down old pods gracefully. The site stays live during the entire deploy.

Monitor the deploy in the dashboard. Traffic is never interrupted.

Step 10: Roll back if needed

If a deploy breaks your app, roll back immediately. In the dashboard, navigate to the project → Deployments tab. Each deployment has a "Rollback" button. Click it to redeploy the last known-good version.

Or via the CLI:

panda projects info my-nextjs-app
# Lists recent deployments with IDs

panda projects deploy my-nextjs-app --deployment-id abc123

The platform redeploys that exact commit and environment variable snapshot.

What you deployed

• A Next.js app in server mode (supports SSR, API routes, Image Optimization)
• A managed PostgreSQL database (optional, link it in the dashboard)
• Automatic HTTPS with a custom domain
• Zero-downtime rolling deploys (new pods start, health checks pass, traffic shifts, old pods shut down)
• Automatic redeploys on every push to main

The free tier includes 5 container apps, 1 managed database, 100 GB bandwidth/month, and 300 build minutes/month. Free-tier apps scale to zero after inactivity (cold start on next request). Upgrade to Pro ($15/mo) for stable nodes with no cold starts.

Start deploying at https://dashboard.pandastack.io.

References

• [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying)
• [PandaStack deployment docs](https://docs.pandastack.io)
• [Let's Encrypt](https://letsencrypt.org)