Deploy Next.js on Temps

Deploy Next.js on your own infrastructure and skip the Vercel bill — full SSR, API routes, middleware, image optimization, and ISR, all running on a VPS you control with automatic HTTPS.

Prerequisites

• A running Temps instance (quickstart)
• A Next.js project in a GitHub, GitLab, Bitbucket, or Gitea repository
• A next.config.js, next.config.mjs or next.config.ts file in the project root, which is how Temps detects Next.js

How Temps runs Next.js

Temps builds your app with your package manager's build script and runs it with next start as a persistent Node.js process. You don't need output: 'standalone' in your next.config.ts; the image contains the full build and node_modules.

Temps runs next start directly, so your package.json start script isn't used. If your app needs a custom server (for example a server.js), deploy it with your own Dockerfile instead.

Builds use a Node.js 22 image, and the app runs on Node.js 22 (Alpine). The Node.js version isn't read from your project.

Quickstart

First, authenticate the CLI against your Temps instance (one time per machine):

# Replace with your own Temps URL, then approve in the browser
npx @temps-sdk/cli login https://temps.example.com

From your Next.js project root, deploy with your preferred package manager:

npx @temps-sdk/cli up

Or via the Temps dashboard:

1. Go to Projects → New Project
2. Connect your repository
3. Temps detects Next.js and configures the build automatically
4. Click Deploy — your app is live with HTTPS in about 2 minutes

What Temps handles automatically

Temps automates the build, TLS, port binding, zero-downtime deploys and rollbacks, and runs your app the same way next start does anywhere else — you can trigger a rollback from the dashboard or CLI at any time.

Environment Variables

Set variables in Project → Settings → Environment Variables or via CLI:

# Set a variable for production
npx @temps-sdk/cli environments vars set DATABASE_URL "postgres://user:pass@host:5432/db" -e production

# Set a variable for production and staging
npx @temps-sdk/cli environments vars set NEXT_PUBLIC_API_URL "https://api.yourdomain.com" -e production,staging

If you leave out -e, the CLI asks which environments to set the variable for.

Your project's variables are passed to the build as well as to the running app. Next.js inlines variables prefixed with NEXT_PUBLIC_ into the browser bundle at build time; all other variables are read by the server at runtime.

Variables are applied when a deployment starts, so changing one doesn't affect the running app until you redeploy:

# After changing a runtime variable, trigger a redeploy
npx @temps-sdk/cli deploy --project my-app

API Routes and Route Handlers

API routes (/app/api/ or /pages/api/) work without any changes. Temps runs your app as a persistent Node.js process, so there are no cold starts — the first request is as fast as any subsequent one.

// app/api/hello/route.ts — works on Temps without changes
export async function GET() {
  return Response.json({ message: "Hello from Temps" });
}

Middleware

Middleware works on Temps without changes. It runs inside the next start server, so the same rules apply as for any self-hosted Next.js app.

ISR and Caching

Incremental Static Regeneration (ISR) works on Temps. The cache is stored on disk inside the container, so it persists between requests.

On redeploy, Temps starts the new container before stopping the old one (zero-downtime). The new container starts with an empty cache, so the first request to each ISR page after a deploy regenerates it, and later requests are served from cache. Temps doesn't offer a persistent volume for the cache; if you need a cache that survives deploys, configure a custom cache handler in Next.js that stores it outside the container.

Monorepos

If your Next.js app is inside a monorepo, set the Root directory in project settings to the subdirectory containing package.json:

my-monorepo/
├── apps/
│   └── web/          ← set Root directory to "apps/web"
│       ├── package.json
│       └── next.config.ts
└── packages/

See Deploy a Project for workspace-aware builds.

Troubleshooting

Health check failing after deploy

Check the deployment logs. A common cause is an app that crashes on startup, for example because of a missing environment variable.

# View live deployment logs
npx @temps-sdk/cli deployments logs --project my-app --follow

Build running out of memory

Next.js builds can be memory-intensive. If the build fails with an out-of-memory error:

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

Set a higher memory limit as an environment variable in your project settings:

NODE_OPTIONS=--max-old-space-size=4096

Environment variables not available at runtime

Check that the variable is set in the correct environment (production vs staging), then redeploy: variables are applied when a deployment starts.

next/image returning 404 for external images

Add your image domains to next.config.ts:

const nextConfig: NextConfig = {
  images: {
    remotePatterns: [
      { protocol: "https", hostname: "your-image-cdn.com" },
    ],
  },
};

Port mismatch

Temps sets the PORT variable for your app (3000 by default), and next start listens on it. To use a different port, set it under Project → Settings → Build & deploy → Deployment. Setting PORT yourself has no effect, because Temps overrides it.

Switching from Vercel

If you're migrating from Vercel, see the Migrate from Vercel guide. Most Next.js apps migrate in under 30 minutes — the main changes are replacing Vercel-specific storage (KV, Blob, Postgres) with standard alternatives.

Platform behavior

These rules apply to every app deployed on Temps, regardless of framework.

Health checks

After your container starts, Temps sends HTTP GET requests to verify it is healthy before routing traffic to it.

• Path: / (the root of your application)
• Success: 2 consecutive responses with a 2xx or 3xx status code
• Timeout: 300 seconds (5 minutes) for the app to become healthy
• Retry interval: every 5 seconds

Connection errors while the app is still starting are retried without penalty. If the app returns 4xx or 5xx errors for 60 consecutive seconds, the deployment fails. Customize the check by adding a .temps.yaml to your repository root:

health:
  path: /health
  status: 200
  interval: 30
  timeout: 5
  retries: 3

Auto-injected environment variables

Temps injects these variables into every deployment automatically:

You do not need to configure these manually. They are available in process.env (Node.js), os.environ (Python), os.Getenv (Go), and the equivalent in other languages.

Next Steps