🏗️ Lumina Boilerplate

Next.js 15 starter template — production-ready dari hari pertama

Fitur · Quick Start · Struktur · Env Variables · Database · Deployment · Saran & Review

✨ Fitur

Boilerplate ini menyediakan fondasi generik yang solid, sehingga Anda bisa langsung fokus membangun fitur bisnis tanpa setup berulang.

🔐 Autentikasi & Otorisasi (RBAC)

Login berbasis username (bukan email) via Supabase Auth — pola shadow email {username}@lumina.internal
Login juga bisa menggunakan nomor HP format 08xxxx
3 level role: SUPER_ADMIN → ADMIN → CLIENT
Edge Middleware — verifikasi JWT kriptografis di setiap request (tanpa DB query untuk route biasa)
Route protection otomatis:
- /admin/* — wajib login (min. ADMIN)
- /admin/settings, /admin/team — khusus SUPER_ADMIN
- /auth/* — redirect ke dashboard jika sudah login

🎨 Dynamic Branding & SEO

Nama situs, logo, warna merek, favicon, OG image — dikontrol dari Admin Panel
Tanpa rebuild atau redeploy — perubahan langsung tampil
CSS variable --brand disuntikkan ke :root tiap request dari nilai database
<title>, <meta description>, Open Graph, dan Web App Manifest — semuanya dinamis dari DB

☁️ File Storage — Cloudflare R2

Upload file ke Cloudflare R2 (S3-compatible, murah, cepat)
Image proxy /api/r2 — mencegah pemblokiran ISP terhadap domain r2.dev
Kompresi otomatis gambar di browser sebelum upload (via browser-image-compression)

📱 Progressive Web App (PWA)

Installable di Android & iOS — tanpa Play Store / App Store
Offline fallback page saat koneksi terputus
Caching strategy per-route (CacheFirst untuk aset, NetworkOnly untuk admin)
Manifest dinamis dari database (nama, warna, ikon)

🖥️ Admin Panel

/admin/dashboard — Overview & statistik
/admin/settings — Branding, SEO, PWA, tema (SUPER_ADMIN only)
/admin/team — Manajemen akun tim (SUPER_ADMIN only)
/admin/profile — Edit profil user yang sedang login
Sidebar navigasi role-aware (menu disesuaikan dengan role)

🧪 E2E Testing

Playwright — sudah dikonfigurasi untuk desktop + mobile (iPhone 13 Pro, Pixel 7)
Test dasar: auth flow, dashboard akses
Mudah ditambah test case sesuai fitur baru

⚡ Quick Start

Prasyarat

Node.js v20+
pnpm v9+
Akun Supabase (gratis)
Akun Cloudflare dengan R2 bucket (gratis 10GB/bulan)
Supabase CLI (npm i -g supabase)

1. Gunakan template ini

# Klik "Use this template" di GitHub, atau clone langsung:
git clone https://github.com/USERNAME/boilerplate-nextjs-lumina.git nama-proyek-baru
cd nama-proyek-baru

2. Install dependencies

pnpm install

3. Setup environment

cp .env.example .env.local

Buka .env.local dan isi semua variabel (lihat bagian Environment Variables di bawah).

4. Setup database

# Link ke Supabase project Anda (hanya sekali)
supabase link --project-ref <project-id>

# Push schema ke Supabase project Anda
pnpm db:push

# Isi data awal (seed 1 akun SUPER_ADMIN + 1 ADMIN untuk testing)
pnpm db:seed

⚠️ Ganti password default (123456) di supabase/seed.ts sebelum digunakan di production!

5. Jalankan development server

pnpm dev

Buka http://localhost:3000 — halaman landing boilerplate.
Login ke admin panel: http://localhost:3000/auth/login

Akun default (dari seed):

Username	Password	Role
`ahink`	`123456`	SUPER_ADMIN
`admin`	`123456`	ADMIN

🗂️ Struktur Folder

boilerplate-nextjs-lumina/
├── src/
│   ├── app/
│   │   ├── admin/              # Semua halaman admin panel
│   │   │   ├── dashboard/      # Halaman utama admin
│   │   │   ├── settings/       # Branding & SEO (SUPER_ADMIN)
│   │   │   ├── team/           # Manajemen tim (SUPER_ADMIN)
│   │   │   └── profile/        # Profil user
│   │   ├── api/
│   │   │   ├── auth/           # Login & logout endpoint
│   │   │   ├── admin/          # Settings & upload API
│   │   │   └── r2/             # Image proxy endpoint
│   │   ├── auth/               # Halaman login
│   │   ├── offline/            # Halaman fallback offline (PWA)
│   │   ├── layout.tsx          # Root layout — dynamic SEO + brand injection
│   │   ├── manifest.ts         # PWA manifest dinamis dari DB
│   │   ├── page.tsx            # Landing page (ganti sesuai kebutuhan)
│   │   └── sw.ts               # Service Worker (Serwist v9)
│   ├── components/
│   │   ├── admin/              # AdminSidebar, AdminHeader, dll
│   │   ├── auth/               # LoginForm
│   │   └── ThemeProvider.tsx   # Injeksi CSS variable brand dari DB
│   ├── context/
│   │   └── AuthContext.tsx     # Client-side auth state (useAuth hook)
│   ├── lib/
│   │   ├── supabase/           # Server & browser Supabase clients
│   │   ├── auth-helpers.ts     # Helper cek session & role sisi server
│   │   └── r2-proxy.ts         # Helper konversi URL → proxy URL
│   ├── styles/                 # Global CSS & design tokens
│   └── middleware.ts           # RBAC route guard (Edge Runtime)
├── supabase/
│   ├── migrations/             # SQL schema migrations
│   └── seed.ts                 # Seeder akun awal (SUPER_ADMIN & ADMIN)
├── tests/                      # E2E tests (Playwright)
├── types/                      # TypeScript global types
├── .env.example                # Template variabel lingkungan
├── next.config.ts
├── playwright.config.ts
└── tailwind.config.ts

🔑 Environment Variables

Salin .env.example ke .env.local dan isi semua nilai berikut:

# ─── Supabase ─────────────────────────────────────────────────────────
NEXT_PUBLIC_SUPABASE_URL=https://xxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGc...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGc...       # ⚠️ Jangan expose ke client!

# ─── Cloudflare R2 ────────────────────────────────────────────────────
R2_ACCOUNT_ID=xxxxxxxxxxxx
R2_ACCESS_KEY_ID=xxxxxxxxxxxx
R2_SECRET_ACCESS_KEY=xxxxxxxxxxxx
R2_BUCKET_NAME=nama-bucket-anda
NEXT_PUBLIC_R2_PUBLIC_URL=https://pub-xxxx.r2.dev
NEXT_PUBLIC_R2_HOSTNAME=pub-xxxx.r2.dev    # Hostname saja, tanpa https://

# ─── App ──────────────────────────────────────────────────────────────
NEXT_PUBLIC_SITE_URL=http://localhost:3000

⚠️ Jangan pernah commit .env.local — file ini sudah ada di .gitignore.

Variabel Opsional (dari proyek asal, bisa dihapus jika tidak pakai)

# Cloudflare Images (untuk optimasi & watermark otomatis — opsional)
CLOUDFLARE_API_TOKEN=your_cloudflare_images_api_token
NEXT_PUBLIC_CLOUDFLARE_IMAGE_DELIVERY_URL=https://imagedelivery.net/your-hash

# Google AI / Gemini (untuk fitur AI description — opsional)
GEMINI_API_KEY=your_google_gemini_api_key

🗄️ Database

Schema database menggunakan Supabase (PostgreSQL). Tabel yang tersedia di boilerplate ini:

Tabel	Deskripsi
`profiles`	Data user (`username`, `full_name`, `phone`, `role`, `avatar_url`)
`web_settings`	Konfigurasi situs (nama, warna, logo, SEO, tema)

Perintah Database

pnpm db:push            # Push schema ke Supabase (production/staging)
pnpm db:seed            # Jalankan seed.ts saja (buat/perbarui akun awal)
pnpm db:reset:local     # Reset + seed database lokal
pnpm db:reset:remote    # Reset + seed database remote
pnpm db:types           # Generate ulang TypeScript types dari schema Supabase

Row Level Security (RLS)

Semua tabel menggunakan RLS — data terlindungi di level database, bukan hanya di level API.

🚀 Deployment

Vercel (Direkomendasikan)

Push repo ke GitHub
Import di vercel.com/new
Tambahkan semua environment variables dari .env.example
Deploy ✅

Catatan: Vercel otomatis mendeteksi Next.js — tidak perlu konfigurasi tambahan.

🧪 Testing

pnpm test:e2e           # Semua test E2E
pnpm test:e2e:mobile    # Hanya mobile (iPhone 13 Pro + Pixel 7)
pnpm test:e2e:ui        # Mode UI interaktif Playwright
pnpm test:e2e:debug     # Mode debug step-by-step

Sebelum menjalankan test, pastikan dev server sedang berjalan (pnpm dev).

🧩 Menambah Fitur Baru

Boilerplate ini dirancang mudah dikembangkan. Untuk menambah fitur:

Buat tabel baru di Supabase (supabase/migrations/)
Generate types ulang: pnpm db:types
Buat API route di src/app/api/nama-fitur/route.ts
Buat halaman admin di src/app/admin/nama-fitur/page.tsx
Tambah menu di src/components/admin/AdminSidebar.tsx

Auth, storage, PWA, dan branding tidak perlu disentuh. ✅

💡 Saran & Catatan untuk Pengguna Baru

⚠️ Yang Perlu Dibersihkan Sebelum Pakai

Item	File	Aksi
Nama package masih `gallery-interactive`	`package.json`	Ubah ke nama proyek baru
Password seed masih default `123456`	`supabase/seed.ts`	Ganti sebelum deploy
Username seed masih `ahink` & `admin`	`supabase/seed.ts`	Sesuaikan dengan tim Anda
Komentar sisa proyek asal	`supabase/seed.ts` (baris akhir)	Hapus komentar UI yang tidak relevan
`.env.example` masih menyebut "Lumina Gallery"	`.env.example` (baris 2)	Update deskripsi sesuai proyek

📦 Dependencies yang Sudah Terinstall

Beberapa library sudah ada dan siap pakai — tidak perlu install ulang:

Library	Kegunaan
`gsap`	Animasi halaman / transisi (dari proyek gallery)
`framer-motion`	Animasi deklaratif React
`lucide-react`	Icon set
`react-image-crop`	Crop avatar/gambar
`browser-image-compression`	Kompresi gambar sebelum upload
`sharp`	Optimasi gambar sisi server

Jika tidak membutuhkan library tertentu, hapus dari package.json untuk mengurangi ukuran bundle.

🗺️ Alur Autentikasi (Shadow Email Pattern)

User input: username "budi"
  ↓
API /api/auth/resolve-login
  ↓
Lookup: profiles WHERE username = 'budi' → email = 'budi@lumina.internal'
  ↓
Supabase Auth login dengan email + password
  ↓
Middleware cek JWT → ambil role dari DB → set x-user-id header
  ↓
Redirect ke /admin/dashboard

🔒 Catatan Keamanan

SUPABASE_SERVICE_ROLE_KEY hanya boleh digunakan di server-side (API routes, seed). Jangan expose ke browser.
Middleware menggunakan supabase.auth.getUser() (verifikasi JWT kriptografis), bukan getSession() (tidak aman untuk keputusan akses).
RLS aktif di semua tabel — bahkan jika ada bug di API, data tetap aman di level database.

📄 Lisensi

MIT — bebas digunakan untuk proyek personal maupun komersial.

Dibuat dengan ❤️ di atas Next.js 15 + Supabase + Cloudflare R2

Diekstrak dari proyek gallery-interactive sebagai boilerplate generik

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.docs		.docs
public		public
src		src
supabase		supabase
test		test
tests		tests
types		types
.gitignore		.gitignore
AUTH_SYSTEM.md		AUTH_SYSTEM.md
README.md		README.md
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
postcss.config.mjs		postcss.config.mjs
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

🏗️ Lumina Boilerplate

✨ Fitur

🔐 Autentikasi & Otorisasi (RBAC)

🎨 Dynamic Branding & SEO

☁️ File Storage — Cloudflare R2

📱 Progressive Web App (PWA)

🖥️ Admin Panel

🧪 E2E Testing

⚡ Quick Start

Prasyarat

1. Gunakan template ini

2. Install dependencies

3. Setup environment

4. Setup database

5. Jalankan development server

🗂️ Struktur Folder

🔑 Environment Variables

Variabel Opsional (dari proyek asal, bisa dihapus jika tidak pakai)

🗄️ Database

Perintah Database

Row Level Security (RLS)

🚀 Deployment

Vercel (Direkomendasikan)

🧪 Testing

🧩 Menambah Fitur Baru

💡 Saran & Catatan untuk Pengguna Baru

⚠️ Yang Perlu Dibersihkan Sebelum Pakai

📦 Dependencies yang Sudah Terinstall

🗺️ Alur Autentikasi (Shadow Email Pattern)

🔒 Catatan Keamanan

📄 Lisensi

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages