Deploy Next.js ke GitHub Pages dengan Custom Domain Gratis

Panduan ini menjelaskan langkah-langkah untuk menyebarkan (deploy) aplikasi Next.js ke GitHub Pages menggunakan GitHub Actions, serta mengonfigurasi custom domain gratis dari GitHub Pages itu sendiri (*.github.io).

1. Prasyarat

Sebelum memulai, pastikan Anda memiliki:

• Akun GitHub
• Node.js v22.x.x terinstal (di lokal)
• Proyek Next.js yang sudah berjalan di lokal
• Git sudah diinisialisasi di dalam folder proyek

2. Struktur Proyek

Pastikan struktur proyek Anda mirip dengan berikut:

my-project/
├── .github/
│   └── workflows/
│       └── deploy.yml
├── pages/
├── public/
├── package.json
├── next.config.js
└── ...

3. Konfigurasi next.config.js

Tambahkan konfigurasi berikut untuk mendukung ekspor ke GitHub Pages:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  basePath: '/nama-repo',
  trailingSlash: true,
};

module.exports = nextConfig;

Gantilah /nama-repo dengan nama repositori Anda di GitHub.

4. Tambahkan Script export di package.json

Buka file package.json, dan pastikan bagian scripts seperti ini:

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

Script export sangat penting karena Next.js tidak otomatis menyediakannya. Perintah ini akan menghasilkan file statis di dalam folder out/ yang akan digunakan untuk GitHub Pages.

5. Workflow GitHub Actions dalam file deploy.yml

Untuk mengotomatisasi proses build dan deploy ke GitHub Pages setiap kali Anda mendorong (push) perubahan ke cabang utama (main), buat file bernama deploy.yml di dalam folder .github/workflows/ dan isi dengan konfigurasi berikut:

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main # Workflow ini akan berjalan saat Anda push ke branch 'main'

permissions:
  contents: write # Memberi hak kepada GitHub Actions untuk menulis ke branch 'gh-pages'

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest # Gunakan runner Ubuntu

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v3 # Mengambil kode dari repositori Anda

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 22 # Versi Node.js yang digunakan (sesuai lokal Anda)
          check-latest: true # Gunakan versi terbaru dari channel 22

      - name: Install Dependencies
        run: npm install # Menginstal semua dependensi dari package.json

      - name: Build and Export
        run: |
          npm run build    # Membuat build aplikasi Next.js
          npm run export   # Mengekspor menjadi file statis di folder 'out'

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3 # Action khusus untuk deploy ke GitHub Pages
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }} # Token default dari GitHub untuk autentikasi
          publish_dir: ./out # Folder yang akan dideploy
          publish_branch: gh-pages # Branch tempat GitHub Pages membaca konten

📌 Penjelasan tambahan:

• File ini sepenuhnya bekerja otomatis setelah Anda push ke main.
• Branch gh-pages akan dibuat dan diperbarui otomatis oleh Actions.
• Anda tidak perlu menulis ke gh-pages secara manual.

6. Aktifkan GitHub Pages

Masuk ke GitHub > Repositori Anda > Settings > Pages, lalu atur:

• Source: Deploy from a branch
• Branch: gh-pages
• Folder: / (root)

Setelah itu, situs Anda akan aktif di:

https://username.github.io/nama-repo/

Pastikan nama repositori sesuai dengan basePath yang Anda tetapkan sebelumnya.

7. Verifikasi Hasil

• Buka tab Actions di GitHub untuk melihat proses build dan deploy.
• Jika sukses, akses URL Pages Anda.
• Pastikan semua aset dimuat dengan benar.

8. 📘 Penjelasan Tambahan: Memahami File .yaml pada GitHub Actions (5W1H)

Sebagai bagian penting dari proses deploy otomatis, mari kita pahami lebih dalam apa itu file .yaml yang digunakan di GitHub Actions, terutama untuk pemula agar tidak bingung atau ragu dalam menggunakannya.

🟦 What — Apa Itu File .yaml dalam GitHub Actions?

File .yaml adalah file konfigurasi teks yang digunakan GitHub Actions untuk mendefinisikan workflow otomatis. Dalam konteks tutorial ini, file tersebut digunakan untuk:

• Menjalankan proses build dan export Next.js
• Men-deploy hasilnya ke GitHub Pages

File ini wajib berada di folder:

.github/workflows/deploy.yml

.yaml adalah singkatan dari YAML Ain’t Markup Language, format ringan seperti JSON, tapi lebih mudah dibaca.

🟨 Why — Mengapa Kita Membutuhkan File .yaml?

GitHub Actions bekerja sepenuhnya berdasarkan deklarasi — artinya, GitHub hanya akan menjalankan sesuatu jika diberi instruksi secara eksplisit melalui file .yaml.

Tanpa file ini:

• GitHub tidak tahu harus melakukan apa setelah push ke repository
• Tidak ada proses otomatisasi build/export
• Website kamu tidak akan pernah ter-deploy ke GitHub Pages secara otomatis

Jadi, file .yaml adalah jantung dari automasi dalam proses CI/CD (Continuous Integration / Continuous Deployment).

🟩 Who — Siapa yang Menggunakan atau Menulis File Ini?

• Anda sendiri (developer) yang menulis file ini sebagai bagian dari setup proyek
• GitHub Actions runner yang menjalankan langkah-langkah di dalam file saat ada event (misalnya push)
• Tidak perlu ditulis oleh orang lain atau pihak ketiga, karena GitHub sudah menyediakan action siap pakai (seperti actions/checkout, peaceiris/actions-gh-pages, dll.)

🟧 Where — Di Mana File Ini Ditempatkan?

Lokasi file .yaml ini harus tepat, yaitu di dalam:

<root-project>/
└── .github/
    └── workflows/
        └── deploy.yml

⚠️ Penamaan folder dan file case-sensitive! Harus .github, bukan .Github atau .GITHUB.

🟥 When — Kapan File Ini Dijalankan?

GitHub Actions akan secara otomatis menjalankan workflow ini ketika ada event tertentu, sesuai yang didefinisikan dalam bagian on:.

Dalam tutorial ini:

on:
  push:
    branches:
      - main

Artinya: ➡️ Setiap kali Anda push ke branch main, workflow akan dijalankan dari awal hingga deploy selesai.

🟪 How — Bagaimana File .yaml Ini Bekerja?

Mari kita bedah alurnya secara natural dan jelas:

• a. Trigger

on:
  push:
    branches:
      - main

➡️ Menunggu event push ke branch main.

• b. Permission

permissions:
  contents: write

➡️ Memberikan izin agar workflow boleh menulis (push) ke branch gh-pages.

• c. Job Utama

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

➡️ Menentukan job yang berjalan di server virtual (runner Linux).

• d. Langkah-langkah (steps)

Berikut ini urutan prosesnya:

1. Ambil kode dari repo:

   uses: actions/checkout@v3
   

2. Instalasi Node.js versi 22:

   uses: actions/setup-node@v3
   with:
     node-version: 22
   

3. Instal dependensi proyek:

   run: npm install
   

4. Build dan export Next.js:

   run: |
     npm run build
     npm run export
   

5. Deploy hasil export ke GitHub Pages:

   uses: peaceiris/actions-gh-pages@v3
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     publish_dir: ./out
   

📦 Hasil dari proses ini akan mendorong isi folder out/ ke branch gh-pages.

9. Penutup

Dengan mengikuti langkah-langkah ini, Anda telah berhasil:

• Men-deploy proyek Next.js ke GitHub Pages
• Menggunakan GitHub Actions untuk otomatisasi
• Mengaktifkan custom domain default dari GitHub (*.github.io) secara gratis

Untuk ekstensi tutorial ini menggunakan domain pihak ketiga (misal Freenom atau domain berbayar), bagian lanjutan dapat disiapkan sesuai permintaan.