Cara Deploy Next.js ke Helipod — Auto Standalone, Zero Config

Next.js adalah framework React paling populer saat ini — dan deploy-nya ke production seharusnya semudah nulis kode-nya. Tapi kenyataannya, banyak developer masih stuck di step Dockerfile, konfigurasi standalone mode, atau setup nginx untuk serve static assets.

Helipod menyelesaikan semua itu secara otomatis.

Ketika kamu connect repository Next.js ke Helipod, Helipack — engine build internal Helipod — akan:

1. Deteksi bahwa project ini adalah Next.js
2. Otomatis inject output: "standalone" ke next.config.js kamu jika belum ada
3. Generate Dockerfile multi-stage yang optimal
4. Build dan deploy

Tidak perlu konfigurasi manual apapun.

Yang Kamu Butuhkan

• Akun Helipod (daftar gratis di helipod.io)
• Repository Next.js di GitHub atau GitLab
• Next.js 13+ (App Router atau Pages Router, keduanya didukung)

Langkah 1: Pastikan next.config.js Siap (Opsional)

Helipack akan otomatis menambahkan output: "standalone" ke konfigurasi Next.js kamu jika belum ada. Tapi jika kamu ingin set secara manual terlebih dahulu:

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "standalone",
  // konfigurasi lainnya...
};

module.exports = nextConfig;

Kenapa standalone? Mode standalone membuat Next.js menghasilkan output yang bisa dijalankan sebagai server Node.js independen — tanpa perlu node_modules penuh. Hasilnya: Docker image yang jauh lebih kecil dan startup yang lebih cepat.

Langkah 2: Connect Repository

Login ke dashboard Helipod, klik New Project, pilih repository Next.js kamu dari GitHub atau GitLab.

Helipod otomatis mendeteksi framework Next.js dan menampilkan konfirmasi di panel sebelah kanan.

Langkah 3: Set Environment Variables

Buka tab Variables dan masukkan environment variables yang dibutuhkan aplikasi kamu:

NEXT_PUBLIC_API_URL=https://api.example.com
DATABASE_URL=postgresql://user:password@host:5432/dbname
NEXTAUTH_SECRET=your-secret-here
NEXTAUTH_URL=https://nama-project.helipod.app

Tips NEXT_PUBLIC_: Variable dengan prefix NEXT_PUBLIC_ akan tersedia di client-side (browser). Variable tanpa prefix hanya tersedia di server-side. Keduanya aman di-set melalui tab Variables Helipod.

NEXTAUTH_URL: Jika kamu menggunakan NextAuth.js, set value ini ke URL production aplikasi kamu — bisa pakai magic domain Helipod dulu, lalu update setelah custom domain aktif.

Langkah 4: Deploy

Klik Deploy. Helipod akan menjalankan proses berikut:

1. Clone repository
2. Deteksi Next.js → inject output: "standalone" jika belum ada
3. Generate Dockerfile multi-stage:
   • Stage deps — install semua dependencies
   • Stage builder — build Next.js dengan next build
   • Stage runner — copy hanya standalone output + static assets
4. Build image (biasanya 3–5 menit untuk project medium)
5. Deploy ke Kubernetes dengan health check otomatis

Pantau proses di tab Deployments → Build logs.

Dockerfile yang Dihasilkan Helipack

Untuk referensi, ini contoh Dockerfile yang dihasilkan Helipack untuk Next.js dengan npm:

# syntax=docker/dockerfile:1
FROM node:20-alpine AS base
RUN apk add --no-cache libc6-compat tini git
WORKDIR /app

FROM base AS deps
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci --prefer-offline --no-audit --no-fund

FROM base AS builder
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ENV NEXT_TELEMETRY_DISABLED=1
ENV NODE_OPTIONS="--max-old-space-size=4096"
RUN --mount=type=cache,target=/root/.npm \
    --mount=type=secret,id=build_env,dst=/app/.env \
    npm run build

FROM node:20-alpine AS runner
RUN apk add --no-cache libc6-compat tini
WORKDIR /app
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
RUN addgroup --system --gid 1001 nodejs && \
    adduser  --system --uid 1001 nextjs

COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static    ./.next/static
COPY --from=builder --chown=nextjs:nodejs /app/public          ./public

USER nextjs
EXPOSE 3000
ENV PORT=3000 HOSTNAME=0.0.0.0
ENTRYPOINT ["/sbin/tini", "--"]
CMD ["node", "server.js"]

Dockerfile ini sudah mengikuti best practice: multi-stage build, non-root user, cache layer yang optimal, dan tini sebagai init process.

Langkah 5: Cek Aplikasi Live

Setelah status berubah ke LIVE, buka URL di tab Settings → Networking & Domains. Format default: nama-project.helipod.app.

Pantau performa di tab Metrics — CPU, Memory, Uptime tersedia real-time.

Konfigurasi Lanjutan dengan helipack.json

Butuh package sistem tambahan atau konfigurasi khusus? Buat helipack.json di root repository:

{
  "run": {
    "port": 3000
  },
  "health": {
    "path": "/api/health",
    "duration": 20
  },
  "packages": {
    "apk": ["sharp"]
  }
}

Tips sharp: Jika menggunakan sharp untuk image optimization, tambahkan ke packages.apk atau pastikan sudah ada di dependencies (bukan devDependencies).

Menggunakan Package Manager Selain npm

Helipack otomatis mendeteksi package manager yang kamu gunakan berdasarkan lock file:

Tidak perlu konfigurasi tambahan — deteksi otomatis.

Tips Optimasi Build Time

Commit lock file — selalu commit package-lock.json, yarn.lock, atau pnpm-lock.yaml. Helipod menggunakan lock file untuk cache layer yang efisien, sehingga build berikutnya jauh lebih cepat.

Gunakan next/image dengan benar — pastikan domain gambar eksternal sudah dikonfigurasi di next.config.js dengan images.remotePatterns.

Environment variables build-time — variable yang dibutuhkan saat next build (bukan runtime) perlu di-set di tab Variables sebelum deploy.

Troubleshooting Umum

Error "output: standalone not found" Biasanya terjadi jika next.config.js terlalu kompleks untuk di-patch otomatis. Tambahkan output: "standalone" secara manual ke config file kamu.

Build gagal: "JavaScript heap out of memory" Helipack sudah set NODE_OPTIONS="--max-old-space-size=4096" secara default. Jika masih error, coba scale up memory pod di Settings → Scaling & Resources saat build, lalu turunkan lagi setelahnya.

Static assets tidak ter-serve Pastikan folder public/ ada di root repository. Helipack otomatis meng-copy folder ini ke dalam image.

NextAuth callback URL salah Update NEXTAUTH_URL di tab Variables ke URL production yang benar, lalu redeploy.

Kesimpulan

Deploy Next.js ke Helipod semudah connect repo dan klik deploy. Helipack mengurus standalone injection, Dockerfile generation, dan optimasi image secara otomatis — kamu tinggal fokus ke kode.

Ingin pakai database bersama Next.js? Baca Deploy PostgreSQL di Helipod dan Panduan Internal Network.

Punya pertanyaan? Hubungi kami di support@helipod.id atau bergabung ke komunitas di hangar.helipod.io.