Cara Install & Penggunaan CLI#

Scaff menyediakan CLI modern dan cepat untuk men-generate starter kit project lengkap dengan tampilan visual siap pakai dalam hitungan detik. Panduan ini mencakup prasyarat, dua mode pemakaian (npx vs global), mode interaktif vs slug langsung, langkah pasca-generate per framework, dan apa yang terjadi di balik layar saat generate.

Prasyarat Sistem#

Sebelum menjalankan Scaff CLI, pastikan perangkatmu memenuhi prasyarat berikut:

1. Node.js v18.0.0 atau lebih baru (wajib untuk semua mode)#

CLI Scaffdev sendiri berjalan di atas Node.js, jadi ini wajib walau kamu memilih template Laravel. Cek versimu:

node --version

Harus keluar v18.x.x atau lebih baru. Kalau belum ada atau terlalu lama, unduh di nodejs.org (pilih LTS). Setelah install, tutup dan buka ulang terminal agar PATH ter-update.

2. Git (wajib)#

Template di-clone via git clone, jadi git harus ada dan bisa diakses dari terminal:

git --version

3. Koneksi internet#

Dibutuhkan untuk dua hal: mengunduh metadata template dari API Scaffdev dan meng-clone repository GitHub. Tidak ada mode offline karena semua repo template diambil live dari GitHub.

4. Prasyarat per framework (sesuai template yang dipilih)#

Unduh Composer di getcomposer.org. CLI memeriksa prasyarat ini otomatis sebelum meng-clone dan akan memberi tahu lebih awal bila ada yang kurang, jadi kamu tidak perlu menebak-nebak.

Catatan penting: Scaffdev saat ini masih dalam masa pengembangan dan baru mendukung 2 framework template yaitu Next.js dan Laravel. Dukungan framework lain akan terus ditambahkan seiring waktu.

Tips Windows: gunakan terminal yang sama untuk semua langkah (CMD, PowerShell, atau Git Bash). Kalau node dikenali di satu terminal tapi tidak di terminal lain, biasanya masalah PATH. Install ulang Node.js dengan opsi "Add to PATH" yang dicentang.

1. Mode Sekali Pakai via npx (Sangat Direkomendasikan)#

Kamu tidak perlu menginstall Scaff secara permanen. Cukup gunakan npx karena setiap eksekusi selalu memakai versi terbaru:

npx scaffdev@latest

Command di atas menampilkan terminal interaktif berisi pertanyaan berurutan. Langkah pertama selalu sama: pilih salah satu dari 3 mode.

? Mau cara apa?
❯ Siap pakai — Langsung generate varian template jadi
  Builder — Racik base + centang integrasi sendiri
  Ambil integrasi — Suntik 1 modul ke project yang sedang dibuka

Mode Siap pakai (butuh CLI apapun):

1. Kategori: E-commerce, Landing Page, atau Portfolio.
2. Framework: Next.js atau Laravel.
3. Varian integrasi: Basic atau yang berintegrasi (mis. Supabase + Midtrans).
4. Nama folder: folder tujuan project (harus kosong atau belum ada).

Mode ini cocok kalau kamu belum memilih template di web atau ingin eksplorasi dulu. Kekurangannya: tiap eksekusi mengunduh ulang CLI terbaru (butuh internet dan sedikit waktu download pertama kali).

Mode Builder (butuh CLI 0.3.0+): setelah pilih mode, pilih kategori → framework → template base (yang disembunyikan dari Builder tidak muncul) → centang integrasi per kategori (maks 1 untuk payment/database/auth/shipping, bebas untuk lainnya) → nama folder. Hasilnya sama persis seperti generate dengan --template=<slug> --with=<kode> yang ekuivalen.

Mode Ambil integrasi (butuh CLI 0.4.0+): tidak membuat folder baru. CLI bekerja di folder project yang sedang dibuka: pilih integrasi → audit keamanan → deteksi framework (otomatis dari package.json/composer.json, atau pilih manual) → preview rencana instalasi → konfirmasi → file disuntik. Detail lengkap di bawah.

Menggunakan Slug Langsung#

Jika kamu sudah memilih template dari website scaffdev.vercel.app/templates, salin command dengan parameter --template agar langsung ke template itu tanpa ditanya lagi:

npx scaffdev@latest --template=ecommerce-supabase-midtrans-nextjs

CLI akan memakai folder default dari slug (atau menanyakan nama folder bila tidak ditentukan).

Untuk menentukan nama folder sekaligus, tulis nama folder di depan flag:

npx scaffdev@latest toko-saya --template=ecommerce-supabase-midtrans-nextjs

Hasilnya: folder toko-saya/ berisi hasil clone template ecommerce-supabase-midtrans-nextjs.

Penting: flag-nya --template=<slug> (dengan tanda =). Tanpa flag ini CLI masuk mode interaktif.

Menambah Modul Integrasi (--with, Builder)#

Status: Live. Flag ini butuh CLI 0.2.0+ dan template/modul yang mendukung
Builder (punya manifest). Lihat tata caranya di Panduan Builder.

Untuk menempel modul integrasi ke template base (mis. tambah Midtrans ke
template polosan):

npx scaffdev@latest toko-saya --template=ecommerce-basic-nextjs --with=midtrans

Aturannya:

• Modul diambil dari repo yang didaftarkan admin (kolom repo modul di menu Integrasi).
• Maksimal 1 per kategori inti (payment/database/auth/shipping); kategori other boleh multi.
• Modul yang tidak cocok framework-nya ditolak dengan pesan jelas, bukan di-skip diam-diam.
• File yang tabrakan dengan base = generate GAGAL eksplisit (tidak ada timpa diam-diam).

Menambah Integrasi ke Project yang Sudah Ada (scaffdev add)#

Butuh CLI 0.4.0+.

Tanpa generate project baru. Jalankan di dalam folder project-mu:

# Interaktif: pilih dari daftar
npx scaffdev add

# Langsung sebut kodenya:
npx scaffdev add supabase

Alurnya selalu sama (prinsip: audit dulu, eksekusi belakangan):

pilih integrasi → security audit → deteksi framework → cek kompatibilitas
→ preview rencana instalasi → konfirmasi → suntik file → merge dependency
→ panduan env → (opsional) install dependency → validasi final

Detail penting:

• Framework terdeteksi otomatis dari package.json / composer.json. Kalau tidak terdeteksi (atau keduanya ada), kamu diminta pilih manual. Modul yang tidak mendukung framework-mu ditolak dengan pesan jelas.
• Kalau file tujuan sudah ada, kamu pilih: Batal (aman, default), Lewati file yang ada, atau Timpa (file lama dibackup dulu ke .scaff/trash/).
• .env tidak pernah disentuh. Key yang belum ada ditambahkan (kosong) ke .env.example.
• Dependency digabung ke package.json/composer.json; konflik versi yang tak terdamaikan menggagalkan secara eksplisit.
• Instalasi dependency (npm install / composer install) selalu ditanyakan dulu, tidak pernah jalan diam-diam.
• Project tanpa scaff.template.json (template orang, project lama — butuh CLI 0.6.0+): CLI memberi peringatan bila terdeteksi jejak modul yang mungkin sudah terpasang manual, menandai folder baru yang akan dibuat di preview, dan menawarkan membuatkan manifest adopsi (default Ya) agar add berikutnya memakai jalur eksak.

Install Dependency Otomatis#

Setelah generate, CLI menawarkan install dependency (default: Ya):

# Jawab "tidak" di prompt, atau paksa via flag:
npx scaffdev@latest toko-saya --template=<slug> --no-install   # lewati
npx scaffdev@latest toko-saya --template=<slug> --install      # langsung jalan (untuk CI)

Template monorepo (install di beberapa folder) didukung via rencana install
di scaff.template.json. CLI menjalankannya berurutan dengan output live.
Gagal install tidak menggagalkan generate (project tetap valid, lanjutkan manual).

Validasi Modul/Template untuk Pembuatnya#

# Dari folder repo modul/template:
scaffdev validate-module .
# Atau langsung dari URL repo:
scaffdev validate-module https://github.com/username/scaff-modul-midtrans.git

Wajib lulus sebelum repo didaftarkan ke admin. Salah tulis seperti --template <slug> (pakai spasi) tidak dikenali. Selalu pakai =.

Security Audit Sebelum Clone#

Butuh CLI 0.3.0+.

Setiap clone (interaktif, slug langsung, tiap modul --with, maupun add) didahului satu pertanyaan:

Run security audit? [Y/n]

Jawab Ya (default): CLI mengunduh arsip repo dan memeriksa pola berbahaya secara statis (lifecycle script, download-lalu-eksekusi, obfuscation, workflow CI, config git) tanpa menjalankan kode apa pun. Hasilnya ditampilkan beserta severity (INFO sampai CRITICAL); temuan HIGH/CRITICAL memblokir default dan hanya lanjut atas konfirmasi eksplisitmu.

Jawab Tidak: CLI memberi warning lalu meminta konfirmasi kedua (Continue without audit?, default-nya Tidak). Tidak ada jalur diam-diam yang melewati audit. Setelah clone, audit lokal (.git/config + hooks) berjalan sebelum dependency diinstall. Detail lengkap: Audit Keamanan Repository.

Kapan memakai mode interaktif vs slug langsung?#

• Interaktif (npx scaffdev@latest tanpa argumen) untuk eksplorasi, belum tahu mau template apa, atau ingin melihat daftar varian yang tersedia.
• Slug langsung (npx scaffdev@latest --template=<slug>) untuk eksekusi cepat dan repeatable: command dari web bisa di-share ke tim, ditempel ke dokumentasi, atau dipakai ulang tanpa salah pilih.

Langkah Lanjutan per Framework#

Setelah generate selesai, CLI menampilkan langkah yang sesuai framework. Jangan lewati karena project belum bisa jalan sebelum langkah ini selesai.

Next.js#

cd nama-project
npm install
cp .env.example .env.local   # lalu isi API key
npm run dev

Penjelasan tiap baris:

1. cd nama-project: masuk ke folder hasil generate.
2. npm install: install dependency (butuh internet, bisa 1–5 menit tergantung template).
3. cp .env.example .env.local: salin kerangka env menjadi file aktif. Di Windows CMD yang tidak punya cp, gunakan copy .env.example .env.local. Lalu isi API key sesuai SETUP.md.
4. npm run dev: jalankan dev server, biasanya di http://localhost:3000.

Laravel#

cd nama-project
composer install
cp .env.example .env         # lalu isi API key
php artisan key:generate
php artisan serve

Penjelasan tiap baris:

1. cd nama-project: masuk ke folder hasil generate.
2. composer install: install dependency PHP.
3. cp .env.example .env: salin kerangka env menjadi file aktif, lalu isi API key.
4. php artisan key:generate: wajib untuk Laravel, men-generate APP_KEY. Tanpa ini aplikasi error.
5. php artisan serve: jalankan dev server, biasanya di http://127.0.0.1:8000.

Detail pengisian key ada di Environment & SETUP.md. Kalau menemui error, lihat Troubleshooting.

2. Mode Instalasi Global#

Bagi developer yang sering membuat project baru dan tidak ingin mengetik npx + download tiap kali, install CLI secara global sekali saja:

npm install -g scaffdev

Setelah terinstall, kamu bisa memanggilnya kapan saja tanpa npx:

# Membuat project baru lewat interactive prompt
scaffdev

# Membuat project dengan template spesifik
scaffdev nama-folder --template=landingpage-basic-nextjs

Perbandingan cepat:

Untuk update versi global:

npm update -g scaffdev

Untuk uninstall global:

npm uninstall -g scaffdev

Versi CLI & Riwayat Perubahan#

Cek versi yang sedang dipakai:

npx scaffdev@latest --version

Aturan versi mengikuti semver pra-1.0: fitur baru yang kompatibel mundur menaikkan minor (0.2.2 → 0.3.0). Changelog lengkap ada di file CHANGELOG.md repo (packages/cli/).

Apa yang Terjadi Saat Generate?#

Ketika kamu menjalankan Scaff CLI, urutan prosesnya selalu sama:

1. Resolusi Slug: CLI menghubungi API Scaffdev untuk mencari URL repository GitHub dan metadata integrasi dari slug yang kamu berikan. Kalau slug salah ketik atau template masih draft, proses berhenti di sini dengan pesan error yang jelas.
2. Pengecekan Prasyarat: CLI memverifikasi versi runtime di komputermu (Node.js, PHP/Composer bila template Laravel, dan git). Kalau ada yang kurang, kamu diberi tahu sebelum clone dimulai.
3. Git Clone: template di-clone langsung ke folder tujuan yang kamu tentukan. Folder harus kosong atau belum ada; CLI tidak akan menimpa diam-diam.
4. Generate Dokumen Otomatis: CLI membuat dua file dari metadata integrasi:
   • .env.example: berisi seluruh environment variable yang dibutuhkan (nama + komentar deskripsi, nilainya kosong).
   • SETUP.md: panduan langkah-demi-langkah cara setup dan konfigurasi API key setiap layanan pihak ketiga.
5. Watermark Kode (butuh CLI 0.7.0+, wajib lisensi): kredit Scaffdev ditulis di akhir README.md, section Atribusi di akhir SETUP.md, dan stempel generator di .scaff/meta.json. Idempoten (aman generate ulang), visual tidak disentuh. Detail: Lisensi.
6. Instruksi Pasca-Generate: CLI mencetak langkah lanjutan sesuai framework (seperti blok Next.js / Laravel di atas).

Setelah proses selesai, cukup buka folder project-mu:

cd nama-project-anda
npm install
npm run dev

Lalu ikuti SETUP.md di folder itu untuk mengisi API key. Tanpa mengisi env, template berintegrasi tetap bisa di-install dan di-build, tapi fitur yang butuh layanan luar (login, payment, ongkir) belum berfungsi sampai key diisi. Ini normal.