# templates/STACK_GUIDE.md - Panduan Stack Standar Tim AI-first
> Versi 1 · 2026-06-01
---
## 1. Pengantar
> ⚠️ **PENTING — panduan ini KHUSUS stack Next.js + Vercel + Supabase**, bukan "universal lintas-stack". Kalau proyekmu pakai stack lain (Python/Django, Go, Rust, PHP/Laravel, dll.), JANGAN paksakan panduan ini — minta AI buatkan panduan sesuai stack-mu (AI deteksi stack via `STACK_DETECTION_PATTERN.md` lalu menyesuaikan). Yang "universal" di kit ini adalah **aturan kerja** (`CLAUDE_universal_v1.md`), bukan pilihan stack.
File ini = **panduan opinionated** untuk stack standar tim AI-first.
Target stack default:
- **Frontend + Backend** → Next.js (lihat STACK_VERSIONS.md untuk versi terbaru) (App Router) + TypeScript 5+
- **Hosting primary** → Vercel (deploy auto dari Git)
- **Database** → Supabase (PostgreSQL managed)
- **UI** → Tailwind 4 + shadcn/ui
- **Future migration path** → Railway / Render (kalau butuh background worker native atau biaya Vercel kelebihan)
### Filosofi opinionated
- **Satu cara untuk satu hal** - jangan campur Pages Router & App Router, jangan campur Server Action & client-fetch untuk mutation.
- **Server-first** - default Server Component, baru ke Client kalau butuh interaktivitas.
- **Vendor-aware tapi tidak vendor-locked** - pakai Vercel sampai mahal, lalu pindah ke Railway/Render. Jangan pakai fitur Vercel-only kalau ada padanan portable.
- **AI-first** - semua konvensi di file ini juga dibaca AI tiap sesi → AI nulis kode yang konsisten tanpa user perlu ulang-ulang aturan.
> *Opinionated* = punya pendapat tegas soal cara kerja. Lawannya *unopinionated* (bebas pilih cara apa saja, tapi tim jadi berantakan).
---
## 2. Next.js App Router Convention
### 2.1. Server Component vs Client Component
**Default = Server Component** (tanpa `'use client'` di atas file).
Kapan pakai `'use client'`:
| Butuh | Pakai `'use client'`? |
|--------------------------------------------------|------------------------|
| `useState`, `useEffect`, `useRef` | YA |
| Event handler (`onClick`, `onChange`, `onSubmit`)| YA |
| Browser API (`window`, `localStorage`, `navigator`) | YA |
| Library client-only (mis. Framer Motion, Chart.js) | YA |
| Cuma render data dari DB / API | TIDAK (Server saja) |
| Form static (pakai Server Action) | TIDAK (Server saja) |
**Pola yang benar**: Server Component sebagai *shell*, Client Component sebagai *island* interaktif kecil.
```tsx
// app/dashboard/page.tsx - Server Component (default)
import { db } from '@/lib/db'
import { LikeButton } from './like-button' // ini Client
export default async function DashboardPage() {
const posts = await db.post.findMany() // fetch langsung di Server
return (
{posts.map((post) => (
{post.title}
{/* island interaktif */}
))}
)
}
```
```tsx
// app/dashboard/like-button.tsx - Client Component
'use client'
import { useState } from 'react'
export function LikeButton({ postId }: { postId: string }) {
const [liked, setLiked] = useState(false)
return
}
```
### 2.2. Data Fetching
**WAJIB**: fetch data di **Server Component** pakai `async/await` langsung.
**JANGAN**: pakai `useEffect` + `fetch` di Client Component untuk initial data.
```tsx
// BENAR - Server Component
export default async function Page() {
const data = await fetch('https://api.example.com/data', {
next: { revalidate: 60 } // ISR: re-fetch tiap 60 detik
}).then(r => r.json())
return
{data.title}
}
// SALAH - useEffect di Client Component untuk initial data
'use client'
export default function Page() {
const [data, setData] = useState(null)
useEffect(() => { fetch('...').then(...) }, []) // loading spinner, SEO buruk
}
```
Kapan pakai client-fetch (`SWR`, `React Query`, `useEffect+fetch`): **hanya** kalau data harus auto-refresh per interval atau triggered by user action setelah halaman load.
### 2.3. Metadata SEO
Setiap route export `metadata` (static) atau `generateMetadata` (dynamic).
```tsx
// Static metadata
export const metadata = {
title: 'Dashboard | Akses',
description: 'Panel admin proyek .',
openGraph: {
title: 'Dashboard | Akses',
description: 'Panel admin proyek .',
images: ['/og-dashboard.png'],
},
}
// Dynamic metadata (per slug / per ID)
export async function generateMetadata({ params }: { params: { slug: string } }) {
const post = await db.post.findUnique({ where: { slug: params.slug } })
return {
title: `${post.title} | Akses`,
description: post.excerpt,
openGraph: { images: [post.coverImage] },
}
}
```
Di `app/layout.tsx` root, set default site-wide:
```tsx
export const metadata = {
metadataBase: new URL('https://.app'),
title: { default: 'Akses', template: '%s | Akses' },
description: 'Manajemen akses & dashboard.',
robots: { index: true, follow: true },
}
```
### 2.4. Form & Mutation
**WAJIB**: pakai **Server Action** untuk semua mutation (create, update, delete).
**JANGAN**: pakai client `fetch('/api/...', { method: 'POST' })` untuk form internal.
```tsx
// app/posts/new/page.tsx - form static + Server Action
import { createPost } from './actions'
export default function NewPostPage() {
return (
)
}
```
```tsx
// app/posts/new/actions.ts - Server Action
'use server'
import { redirect } from 'next/navigation'
import { db } from '@/lib/db'
import { revalidatePath } from 'next/cache'
export async function createPost(formData: FormData) {
const title = formData.get('title') as string
const content = formData.get('content') as string
// validasi (pakai Zod di produksi)
if (!title || title.length < 3) throw new Error('Title min 3 char')
await db.post.create({ data: { title, content } })
revalidatePath('/posts')
redirect('/posts')
}
```
Kalau butuh feedback interaktif (loading, error) di form → wrap dengan Client Component pakai `useActionState` (React 19).
### 2.5. Loading & Error State (File Convention)
Next.js App Router auto-render file ini di tiap route segment:
```text
app/
├── dashboard/
│ ├── page.tsx // halaman utama
│ ├── loading.tsx // muncul saat page.tsx masih loading data
│ ├── error.tsx // muncul kalau page.tsx throw error
│ └── not-found.tsx // muncul kalau notFound() dipanggil
```
```tsx
// app/dashboard/loading.tsx
export default function Loading() {
return