Next.js

Apa yang dideteksi Zenavo

Repositori dengan next di package.json dibangun dengan zbpack sebagai Node.js, framework next.js:

Langkah	Perintah
Instal	npm install, pnpm install, yarn install, atau bun install, mengikuti lockfile di repositori (yarn bila tidak ada)
Build	skrip build, biasanya next build
Start	skrip start, biasanya next start

Versi Node.js diambil dari engines.node di package.json (22 bila tidak diatur). Commit lockfile Anda agar instalasinya dapat direproduksi dan package manager yang benar dipakai.

next start mendengarkan di $PORT, yang diatur Zenavo ke 8080, di semua interface, jadi aplikasi bawaan tidak perlu diubah:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

Deploy

1. Add Service → GitHub, pilih repositori dan branch.
2. Tambahkan variabel yang dibutuhkan aplikasi (lihat di bawah) lalu klik Next.
3. Pastikan pratinjau menampilkan nodejs dan next.js, lalu klik Deploy.
4. Di tab Networking, buat domain atau pasang domain Anda sendiri.

Variabel lingkungan

• Variabel sisi server (process.env.DATABASE_URL di route handler, server component, getServerSideProps) dibaca saat aplikasi berjalan: atur di tab Variable lalu deploy ulang.
• Variabel NEXT_PUBLIC_* ditulis ke bundle JavaScript oleh next build, jadi harus ada saat build. Variabel di tab Variable hanya diberikan ke aplikasi yang berjalan, jadi atur variabel ini di Settings → Build → Build arguments, misalnya NEXT_PUBLIC_API_URL=https://api.example.com, atau NEXT_PUBLIC_API_URL=${API_URL} untuk memakai ulang variabel. Variabel ini sampai ke build tanpa Dockerfile; lihat argumen build.
• Alamat situs itu sendiri adalah ZENAVO_<PORT>_URL, misalnya ${ZENAVO_WEB_URL}, setelah port punya domain. Gunakan untuk NEXTAUTH_URL atau sejenisnya.

Hubungkan database

Tambahkan PostgreSQL ke proyek dan rujuk variabelnya dari layanan Next.js:

DATABASE_URL=${POSTGRESQL_CONNECTION_STRING}

Prisma, Drizzle, dan pg semuanya menerima URL ini. Jalankan migrasi saat layanan mulai, karena build tidak bisa menjangkau database: skrip predeploy berjalan sebelum start.

"scripts": {
  "build": "next build",
  "predeploy": "prisma migrate deploy",
  "start": "next start"
}

Image lebih kecil dengan output: 'standalone'

Dengan output: 'standalone' di next.config.js, next build menulis server mandiri ke .next/standalone. zbpack tidak memakainya, jadi untuk memanfaatkannya, tambahkan Dockerfile:

FROM node:22-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
ARG NEXT_PUBLIC_API_URL
RUN npm run build

FROM node:22-alpine
WORKDIR /app
ENV NODE_ENV=production HOSTNAME=0.0.0.0
COPY --from=build /app/.next/standalone ./
COPY --from=build /app/.next/static ./.next/static
COPY --from=build /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]

HOSTNAME=0.0.0.0 membuat server standalone mendengarkan di semua interface, dan port-nya berasal dari EXPOSE (di sini 3000). Setiap variabel yang dibutuhkan build, seperti NEXT_PUBLIC_API_URL, mendapat baris ARG sebelum RUN npm run build dan nilai di Settings → Build → Build arguments.

Masalah umum

Gejala	Penyebab
Build gagal dengan JavaScript heap out of memory	Aplikasi besar butuh memori lebih dari yang didapat build secara bawaan. Tambahkan NODE_OPTIONS=--max-old-space-size=4096 di Settings → Build → Build arguments (dengan Dockerfile sendiri, tambahkan juga ARG NODE_OPTIONS di stage build), atau rampingkan build.
Nilai NEXT_PUBLIC_* bernilai undefined di browser	Nilainya hanya ada di tab Variable. Atur sebagai argumen build lalu deploy ulang. Dengan Dockerfile sendiri, deklarasikan juga dengan ARG sebelum next build.
Gambar dari next/image gagal	Gambar remote membutuhkan images.remotePatterns di next.config.js.
Server standalone tidak bisa dijangkau	HOSTNAME bukan 0.0.0.0, sehingga hanya mendengarkan di hostname kontainer.