📘 Project Guidelines — Amir App

⚠️ MANDATORY: Semua AI Agent WAJIB membaca file ini sebelum menulis kode apapun.

1. Project Overview

Key	Value
App Name	Amir App
Framework	Next.js 16.3.0 (App Router)
React	React 19.2.8
Language	TypeScript 6.0.3 (Strict Mode)
Styling	Tailwind CSS v4.3.3
PWA	Serwist v9.5.12
Linting	ESLint v9.21.0 + eslint-config-next 16.3.0
Node	≥ 18
Package Mgr	Bun v1.3.14

2. ⚠️ Next.js 16 — Breaking Changes

‼️ JANGAN gunakan pengetahuan lama tentang Next.js.
   Versi ini memiliki breaking changes.
   SELALU baca docs di: node_modules/next/dist/docs/
   sebelum menulis kode apapun.

Yang harus diperhatikan:

App Router ONLY — Tidak ada pages/ directory
React 19 — Gunakan fitur terbaru (Server Components default)
Metadata API — Gunakan export const metadata atau generateMetadata()
Font Loading — Gunakan next/font/google (sudah setup: Geist, Geist_Mono)
Image Component — Gunakan next/image dengan prop terbaru
Cek deprecation notices — Ikuti warning dari Next.js

3. Folder Structure

Init-nextjs-app/
├── src/                        # 📂 All source code disatukan di dalam src/
│   ├── app/                    # Next.js App Router
│   │   ├── layout.tsx          # Root layout (html lang, metadata, ThemeProvider)
│   │   ├── page.tsx            # Homepage (i18n)
│   │   ├── globals.css         # Global styles + Tailwind config (@theme inline)
│   │   ├── manifest.ts         # PWA manifest
│   │   ├── sw.ts               # Service Worker (Serwist)
│   │   ├── providers.tsx       # ThemeProvider wrapper (next-themes)
│   │   ├── robots.ts           # Robots.txt generator
│   │   ├── sitemap.ts          # Sitemap generator
│   │   ├── favicon.ico
│   │   ├── _components/        # App-wide UI components (LanguageSwitcher, ThemeSwitcher)
│   │   └── demo-encryption/    # Demo Keamanan ID (page.tsx, DemoClient.tsx, actions.ts)
│   ├── i18n/                   # i18n configuration
│   │   └── config.ts          # Locale list & types
│   ├── lib/                    # Shared utilities
│   │   ├── crypto.ts          # Enkripsi & Dekripsi AES-256-GCM (server-only)
│   │   ├── obfuscator.ts      # Penyamaran & Deobfuscation ID Sqids
│   │   ├── dictionaries.ts    # Dictionary loader (server-only)
│   │   ├── i18n-server.ts     # Cookie-based locale retriever (server-only)
│   │   ├── i18n-actions.ts    # Server action for changing locale cookie
│   │   └── seo.ts             # SEO helpers & JSON-LD
│   ├── dictionaries/           # Translation files
│   │   ├── id.json            # 🇮🇩 Bahasa Indonesia (default)
│   │   └── en.json            # 🇺🇸 English
│   └── proxy.ts                # Pass-through middleware proxy
├── public/                     # Static assets & PWA icons
├── prompt_ai/                  # AI prompt templates (bukan source code)
├── .env                        # Common env (semua environment)
├── .env.development            # Dev-only env overrides
├── .env.production             # Prod-only env overrides
├── .env.example                # Template referensi (committed ke git)
├── AGENTS.md                   # AI Agent rules (Next.js & skill rules)
├── GUIDELINE.md                # 📌 File ini — project guidelines
├── next.config.ts              # Next.js configuration
├── tsconfig.json               # TypeScript config
├── eslint.config.mjs           # ESLint config (ESLint v9)
├── postcss.config.mjs          # PostCSS config (Tailwind CSS v4)
└── package.json

Konvensi Penamaan Folder Baru:

Feature/Module → app/(group)/feature-name/
Components → app/_components/ atau co-locate
Hooks → app/_hooks/ atau co-locate dengan feature
Utils/Lib → lib/ di root
Types → types/ di root atau co-locate

4. Environment Variables

File Priority (urutan loading Next.js):

.env — Base/common (selalu di-load)
.env.development — Override untuk NODE_ENV=development
.env.production — Override untuk NODE_ENV=production
.env.local — Override tertinggi, TIDAK committed

Aturan Naming:

Prefix	Accessible di	Contoh
`NEXT_PUBLIC_`	Client + Server	`NEXT_PUBLIC_APP_URL`
Tanpa prefix	Server ONLY	`DATABASE_URL`, `AUTH_SECRET`

⚠️ JANGAN PERNAH:

Menyimpan secret/key di file dengan prefix NEXT_PUBLIC_
Hardcode URL atau API key langsung di source code
Commit .env.local ke git

5. Coding Standards

TypeScript

Strict mode ON — Tidak boleh menggunakan any tanpa justifikasi
Gunakan interface untuk object shapes, type untuk unions/intersections
Semua function harus memiliki return type yang eksplisit (kecuali JSX components)
Gunakan path alias @/* (sudah di-setup di tsconfig)

// ✅ Benar
import { LanguageSwitcher } from "@/app/_components/language-switcher";

// ❌ Salah
import { LanguageSwitcher } from "../../../_components/language-switcher";

React / Next.js

Server Components adalah default — Hanya gunakan "use client" jika benar-benar butuh interaktivitas (state, effects, event handlers)
Gunakan async Server Components untuk data fetching langsung
JANGAN gunakan useEffect untuk data fetching — gunakan Server Components atau Server Actions
Pisahkan komponen besar menjadi komponen kecil yang reusable

Routing & State Management

Gunakan Flat Routing + SearchParams untuk mengalirkan ID dari halaman/segmen sebelumnya ke segmen yang lebih dalam.
HINDARI Nested Dynamic Routes (folder bertingkat terlalu dalam) untuk menjaga struktur folder tetap rata (flat) dan mudah dinavigasi.
HINDARI Shared Layout & React Context untuk meneruskan parameter routing antar halaman; gunakan query parameters (searchParams) agar data fetching tetap optimal di Server Components.

File Naming

Tipe	Format	Contoh
Route Page	`page.tsx`	`app/about/page.tsx`
Layout	`layout.tsx`	`app/dashboard/layout.tsx`
Component	`kebab-case.tsx`	`user-card.tsx`
Hook	`use-*.ts`	`use-auth.ts`
Utility	`kebab-case.ts`	`format-date.ts`
Type	`kebab-case.ts`	`user-types.ts`
Constant	`UPPER_SNAKE_CASE`	`API_ENDPOINTS`

6. Styling — Tailwind CSS v4 & Theming

Setup yang sudah ada:

globals.css menggunakan @import "tailwindcss" (Tailwind v4 syntax)
@variant dark (&:where(.dark, .dark *)); untuk class-based dark mode di Tailwind v4
Standard CSS variables & design tokens untuk :root (Light Theme) dan .dark (Dark Theme):
- --background, --foreground, --card, --primary, --secondary, --muted, --accent, --border, --ring, dll.
@theme inline block untuk memetakan token ke class Tailwind (bg-background, text-foreground, bg-primary, border-border, dll.)
<ThemeProvider> via next-themes (attribute="class", defaultTheme="system") untuk pengubahan tema tanpa FOUC
Komponen ThemeSwitcher (src/app/_components/theme-switcher.tsx) untuk memilih tema (Light ☀️, Dark 🌙, System 💻). Catatan: Kode dan fungsinya tetap dibuat, namun defaultnya di-hide / gone di UI utama sampai user meminta request show.

🎨 Mandatory Skills untuk Styling & UI Design:

Setiap pengerjaan UI, layout, komponen, dan styling WAJIB memanfaatkan & mengombinasikan skill-skill berikut:

using-superpowers (.agents/skills/using-superpowers) — Digunakan sebelum eksekusi untuk memastikan workflow penemuan & pemanggilan skill dilakukan secara terstruktur.
hallmark (.agents/skills/hallmark) — Anti-AI-slop design skill untuk variasi struktur UI/layout, komponen 8-state, microinteractions, responsivitas mobile-first, dan kualitas visual premium.
ui-ux-pro-max (.agents/skills/ui-ux-pro-max) — Design intelligence & guidelines untuk pemilihan color palette, typography pairing, standar aksesibilitas (WCAG/contrast), touch targets, dan UX pre-delivery checklist.
tailwind-design-system (.agents/skills/tailwind-design-system) — Membangun design tokens, variasi komponen, pola responsif, dan pengorganisasian Tailwind CSS v4 secara sistematis dan terstandar.

Aturan:

Gunakan Tailwind classes — Hindari inline style
Gunakan CSS variables di @theme inline untuk custom values
Dark mode harus selalu di-support di semua komponen UI
Responsive design — Mobile-first approach (sm:, md:, lg:)
JANGAN install Tailwind plugins tanpa konfirmasi user

/* ✅ Tambah design token baru di globals.css */
:root {
  --custom-color: #ffffff;
}

.dark {
  --custom-color: #000000;
}

@theme inline {
  --color-custom: var(--custom-color);
}

7. PWA (Progressive Web App)

Setup:

Serwist v9.5.12 untuk Service Worker
src/app/sw.ts — Service Worker source
src/app/manifest.ts — Web App Manifest
PWA di-disable saat development (next.config.ts)

Aturan:

Update manifest.ts jika mengubah app name, icon, atau theme
Jangan edit sw.ts kecuali butuh custom caching strategy
Icon PWA harus tersedia di /public/
Test PWA di production build (bun run build && bun start)

8. Internationalization (i18n)

Arsitektur:

Project ini menggunakan Cookie & Localization-based i18n tanpa meletakkan locale di URL path:

Tanpa prefix routing ([lang]) — URL tetap bersih (/, /about, /demo-encryption).
Cookie NEXT_LOCALE — Menyimpan preferensi bahasa pengguna (id atau en).
i18n-server.ts — Helper server-side untuk membaca cookie NEXT_LOCALE dan memuat dictionary terkait.
LanguageSwitcher — Komponen UI client untuk mengubah bahasa via Server Action setLocaleAction(). Catatan: Kode dan fungsinya tetap dibuat, namun defaultnya di-hide / gone di UI utama sampai user meminta request show.

Locales:

Locale	Bahasa	Default
`id`	🇮🇩 Bahasa Indonesia	✅ Ya
`en`	🇺🇸 English	❌ Tidak

File Structure:

src/i18n/config.ts            # Locale list & Locale type
src/dictionaries/id.json       # Translations (ID)
src/dictionaries/en.json       # Translations (EN)
src/lib/dictionaries.ts        # Dictionary loader (server-only)
src/lib/i18n-server.ts        # Server locale & dictionary fetcher
src/lib/i18n-actions.ts       # Server Action for setting locale cookie
src/app/_components/language-switcher.tsx # UI Switcher Component

Cara Menggunakan di Server Component:

import { getCurrentDictionary } from "@/lib/i18n-server";

export default async function Page() {
  const { locale, dict } = await getCurrentDictionary();

  return <h1>{dict.home.title}</h1>;
}

Cara Menambahkan Translation Baru:

Tambahkan key baru di kedua file: dictionaries/id.json dan dictionaries/en.json
Gunakan nested object untuk grouping (misal: nav.home, error.notFound)
JANGAN hardcode string UI — selalu gunakan dictionary

Cara Menambahkan Locale Baru:

Update i18n/config.ts — tambahkan locale ke array locales
Buat file dictionaries/{locale}.json dengan semua key yang sama
Update lib/dictionaries.ts — tambahkan import baru

⚠️ Aturan i18n:

TIDAK PERLU membuat folder app/[lang]/
Gunakan getCurrentDictionary() pada Server Components untuk mengambil locale dan dict
Dictionary hanya di server — gunakan import "server-only"
JANGAN import dictionary di client component — pass translations sebagai props

9. Performance & SEO

Wajib dilakukan:

Gunakan next/image untuk semua gambar (JANGAN gunakan tag HTML <img> biasa)
Gunakan next/font untuk fonts (sudah setup Geist)
Set metadata di setiap layout.tsx / page.tsx
Gunakan semantic HTML (<main>, <section>, <article>, dsb)
Satu <h1> per halaman
Lazy load komponen berat dengan dynamic() import

Metadata Template:

import type { Metadata } from "next";

export const metadata: Metadata = {
  title: "Page Title — Amir App",
  description: "Deskripsi halaman yang informatif",
};

10. Git Conventions

Branch Naming:

feature/nama-fitur
fix/deskripsi-bug
chore/deskripsi-task

Commit Message Format:

type(scope): description

feat(auth): add login page
fix(dashboard): resolve chart rendering
chore(deps): update next.js to 16.x
style(ui): adjust header spacing

Yang TIDAK boleh di-commit:

node_modules/
.next/
.env.local
File temporary / scratch

Yang BOLEH di-commit:

.env (common, tanpa secrets)
.env.development (tanpa secrets)
.env.production (tanpa secrets — secrets via hosting platform)
.env.example (template referensi)

11. Commands Reference

Command	Fungsi
`bun run dev`	Jalankan dev server (dengan webpack)
`bun run build`	Build production bundle (dengan webpack)
`bun start`	Jalankan production server
`bun run lint`	Jalankan ESLint
`bun run cli`	Jalankan CLI helper lokal
`bun install`	Install semua dependencies
`bun add <pkg>`	Tambah dependency baru
`bun add -d <pkg>`	Tambah dev dependency baru

Note: Flag --webpack sudah di-set di package.json scripts.

12. Checklist Sebelum Push

bun run lint — Tidak ada error
bun run build — Build sukses tanpa error
Tidak ada console.log yang tertinggal (gunakan LOG_LEVEL)
Semua halaman punya metadata (title, description)
Dark mode berfungsi dengan baik
Responsive di mobile dan desktop
Environment variables baru sudah ditambahkan ke .env.example
Translation tersedia di semua locale (id.json & en.json)

13. Rules untuk AI Agent

✅ HARUS:

Baca AGENTS.md dan GUIDELINE.md sebelum menulis kode
Baca Next.js 16 docs di node_modules/next/dist/docs/ untuk fitur yang akan digunakan
Gunakan TypeScript strict — no implicit any
Gunakan path alias @/*
Support dark mode di semua UI yang dibuat
Gunakan Server Components sebagai default
Tambahkan metadata di setiap halaman baru
Update .env.example jika menambah env variable baru
Tambahkan translations di kedua locale file (id.json & en.json)
Gunakan getCurrentDictionary() dari @/lib/i18n-server di Server Component
Gunakan next/image (Image component dari next/image) untuk semua gambar di component React/Next.js
Gunakan Flat Routing + SearchParams saat membutuhkan ID atau state dari halaman/segmen sebelumnya.
⚠️ WAJIB HAPUS rute demo (app/demo-encryption/) saat mulai pengerjaan web riil agar rute demo ini tidak masuk ke build produksi.
Default Hide/Gone Theme & Language Switcher — Kode dan fungsi ThemeSwitcher dan LanguageSwitcher tetap dibuat dan disiapkan, tetapi defaultnya di-hide / gone di UI utama sampai user meminta request show.
Wajib Gunakan Skills Styling — Untuk setiap pengerjaan UI, layout, dan CSS styling, AI agent HARUS meng-invoke dan mematuhi aturan dari using-superpowers, hallmark, ui-ux-pro-max, dan tailwind-design-system.

❌ JANGAN:

JANGAN menggunakan pages/ directory
JANGAN menggunakan API/syntax Next.js versi lama tanpa verifikasi
JANGAN hardcode values yang seharusnya di environment variable
JANGAN menggunakan "use client" tanpa alasan yang jelas
JANGAN menginstall dependency baru tanpa konfirmasi user
JANGAN menghapus atau mengubah konfigurasi existing tanpa konfirmasi
JANGAN menggunakan any type
JANGAN menulis CSS inline — gunakan Tailwind classes
JANGAN hardcode string UI — gunakan dictionary i18n
JANGAN membuat dynamic route [lang] di URL
JANGAN menggunakan tag HTML <img> biasa di component React/Next.js — selalu gunakan next/image untuk optimasi performa dan SEO
JANGAN menggunakan Nested Dynamic Routes yang terlalu dalam.
JANGAN menggunakan Shared Layout & React Context untuk sekadar membagikan parameter routing antar halaman.
JANGAN menampilkan ThemeSwitcher dan LanguageSwitcher di UI utama secara default tanpa permintaan eksplisit dari user (tetap jaga kodenya agar siap digunakan kapan saja).

📅 Last updated: 2026-08-13

Uh oh!

FilesExpand file tree

GUIDELINE.md

Latest commit

History

GUIDELINE.md

File metadata and controls

📘 Project Guidelines — Amir App

1. Project Overview

2. ⚠️ Next.js 16 — Breaking Changes

Yang harus diperhatikan:

3. Folder Structure

Konvensi Penamaan Folder Baru:

4. Environment Variables

File Priority (urutan loading Next.js):

Aturan Naming:

⚠️ JANGAN PERNAH:

5. Coding Standards

TypeScript

React / Next.js

Routing & State Management

File Naming

6. Styling — Tailwind CSS v4 & Theming

Setup yang sudah ada:

🎨 Mandatory Skills untuk Styling & UI Design:

Aturan:

7. PWA (Progressive Web App)

Setup:

Aturan:

8. Internationalization (i18n)

Arsitektur:

Locales:

File Structure:

Cara Menggunakan di Server Component:

Cara Menambahkan Translation Baru:

Cara Menambahkan Locale Baru:

⚠️ Aturan i18n:

9. Performance & SEO

Wajib dilakukan:

Metadata Template:

10. Git Conventions

Branch Naming:

Commit Message Format:

Yang TIDAK boleh di-commit:

Yang BOLEH di-commit:

11. Commands Reference

12. Checklist Sebelum Push

13. Rules untuk AI Agent

✅ HARUS:

❌ JANGAN: