Instalasi Laravel 12 + Breeze Inertia React TS

Instalasi Laravel 12 + Breeze Inertia React TypeScript

Di lesson ini, kita akan setup project HRIS dari nol hingga siap development. Ini adalah lesson praktik pertama - pastikan Anda sudah menyiapkan software dari checklist di Lesson 1! Bayangkan proses instalasi ini seperti membangun fondasi rumah - jika fondasinya kuat dan benar, seluruh bangunan di atasnya akan kokoh.

Laravel 12 adalah framework PHP paling populer yang akan menjadi "backbone" aplikasi HRIS kita. Dengan Composer, kita bisa mendownload Laravel beserta ribuan package pendukung dalam satu command. Breeze adalah "starter kit" yang menyediakan authentication siap pakai - artinya login, register, forgot password sudah jadi tanpa perlu coding dari nol.

Stack yang kita pilih adalah Inertia.js + React + TypeScript. Inertia memungkinkan kita membuat SPA (Single Page Application) tanpa perlu membuat API terpisah. React memberikan UI yang interaktif dan reusable. TypeScript menambahkan type safety yang mencegah banyak bug sebelum runtime.

Estimasi waktu bervariasi tergantung level Anda (lihat Overview di atas) dan kecepatan internet saat download dependencies. Jangan khawatir jika ada error - di akhir lesson ada tabel troubleshooting yang membahas error-error umum beserta solusinya.

Diagram Alur Instalasi

Berikut adalah alur langkah-langkah instalasi yang akan kita lakukan:

Step 1: Buat Project Laravel

Langkah pertama adalah membuat project Laravel baru menggunakan Composer. Bayangkan Composer seperti "toko bangunan online" - Anda pesan Laravel, dan Composer akan mendownload semua material yang diperlukan (framework, library, dependencies) dalam satu paket lengkap.

Laravel 12 adalah versi terbaru yang membutuhkan PHP 8.2 atau lebih tinggi. Versi ini membawa banyak peningkatan performa dan fitur baru yang akan sangat berguna untuk aplikasi HRIS kita. Pastikan versi PHP Anda sudah sesuai sebelum melanjutkan.

Kita akan membuat project dengan nama HRISApp. Nama ini akan menjadi nama folder project sekaligus namespace dasar aplikasi. Pastikan Anda berada di direktori yang tepat sebelum menjalankan command - biasanya di folder htdocs (XAMPP), www (Laragon), atau direktori development Anda.

Proses instalasi akan memakan waktu 3-5 menit tergantung kecepatan internet. Selama proses berjalan, Composer akan menampilkan progress download dan instalasi package. Anda akan melihat banyak nama package yang terinstall - ini normal dan menunjukkan bahwa proses berjalan dengan benar.

# ========================================
# LANGKAH 1: BUAT PROJECT LARAVEL BARU
# ========================================

# LANGKAH 1.1: Download dan install Laravel 12
# - composer = package manager PHP
# - create-project = buat project baru dari package
# - laravel/laravel = nama package Laravel
# - HRISApp = nama folder project yang akan dibuat
composer create-project laravel/laravel HRISApp

# ========================================
# LANGKAH 2: MASUK KE FOLDER PROJECT
# ========================================

# LANGKAH 2.1: Pindah ke direktori project
# Semua command selanjutnya HARUS dijalankan dari folder ini
cd HRISApp

# ========================================
# LANGKAH 3: VERIFIKASI INSTALASI
# ========================================

# LANGKAH 3.1: Cek versi Laravel yang terinstall
# Hasil yang diharapkan: "Laravel Framework 12.x.x"
php artisan --version

Kode di atas mengimplementasikan proses pembuatan project Laravel baru. Beberapa poin penting yang perlu diperhatikan:

Step 2: Install Laravel Breeze dengan React TypeScript

Laravel Breeze adalah authentication starter kit resmi dari Laravel yang menyediakan implementasi login, register, reset password, dan email verification dalam waktu singkat. Bayangkan Breeze seperti "paket furniture siap pakai" - daripada membuat meja, kursi, dan lemari sendiri, Anda beli paket yang sudah jadi dan tinggal pasang.

Yang membuat Breeze istimewa adalah tersedianya berbagai "stack" frontend. Anda bisa memilih antara Blade (PHP templating), Livewire (PHP + JavaScript), Vue, atau React sebagai frontend. Untuk kursus HRIS ini, kita memilih stack React dengan TypeScript karena memberikan pengalaman development yang paling modern.

TypeScript adalah "superset" dari JavaScript yang menambahkan static typing. Dengan TypeScript, kesalahan seperti typo nama variable atau salah tipe data akan terdeteksi SEBELUM kode dijalankan. Ini sangat membantu mengurangi bug dan meningkatkan produktivitas development.

Setelah instalasi Breeze selesai, Anda akan mendapatkan halaman Login, Register, Forgot Password, dan Dashboard yang sudah berfungsi. Semua halaman ini menggunakan React + TypeScript + Tailwind CSS, sehingga mudah untuk dikustomisasi sesuai kebutuhan aplikasi HRIS.

# ========================================
# LANGKAH 1: INSTALL BREEZE PACKAGE
# ========================================

# LANGKAH 1.1: Download Breeze dari Packagist
# - --dev = install sebagai development dependency
# - Artinya package ini tidak diperlukan di production
composer require laravel/breeze --dev

# ========================================
# LANGKAH 2: SETUP BREEZE REACT + TYPESCRIPT
# ========================================

# LANGKAH 2.1: Jalankan installer Breeze
# - react = gunakan React sebagai frontend
# - --typescript = aktifkan TypeScript untuk type safety
# Command ini akan:
# - Membuat halaman auth (Login, Register, dll)
# - Mengkonfigurasi Vite sebagai bundler
# - Setup Tailwind CSS
# - Install Inertia.js sebagai bridge
php artisan breeze:install react --typescript

# ========================================
# LANGKAH 3: INSTALL NPM DEPENDENCIES
# ========================================

# LANGKAH 3.1: Download semua package JavaScript
# Ini akan membuat folder node_modules dengan ribuan package
# Proses ini memakan waktu 2-5 menit tergantung internet
npm install

Kode di atas mengimplementasikan instalasi Breeze dengan stack React TypeScript. Proses ini akan menginstall banyak komponen sekaligus.

Step 3: Setup Database

Sebelum aplikasi bisa menyimpan data, kita perlu membuat database MySQL. Bayangkan database seperti "lemari arsip digital" yang menyimpan semua data karyawan, absensi, gaji, dan informasi HRIS lainnya secara terstruktur dan mudah dicari.

Laravel menggunakan file .env untuk menyimpan konfigurasi database. Ini memungkinkan kita menggunakan database berbeda di development dan production tanpa mengubah kode. Konsep ini disebut "Environment Variables" - nilai yang berbeda-beda tergantung di mana aplikasi dijalankan.

Mengapa perlu database terpisah untuk development dan production? Karena di development kita bebas bereksperimen (hapus data, reset table), sedangkan di production data harus dijaga ketat. Dengan .env, kita cukup ganti nilai dan aplikasi otomatis terhubung ke database yang tepat.

3a. Buat Database MySQL

Ada dua cara untuk membuat database: via terminal MySQL atau melalui phpMyAdmin. Keduanya menghasilkan hasil yang sama - pilih yang paling nyaman untuk Anda.

# ========================================
# LANGKAH 1: BUAT DATABASE VIA TERMINAL
# ========================================

# LANGKAH 1.1: Buat database dengan nama hris_app
# - -u root = login sebagai user root
# - -p = prompt untuk password (kosongkan jika tidak ada password)
# - -e = execute SQL command langsung
mysql -u root -p -e "CREATE DATABASE hris_app"

# ========================================
# LANGKAH 2: ALTERNATIF VIA PHPMYADMIN
# ========================================

# LANGKAH 2.1: Buka browser dan akses phpMyAdmin
# URL: http://localhost/phpmyadmin

# LANGKAH 2.2: Klik "New" di sidebar kiri

# LANGKAH 2.3: Ketik "hris_app" di field Database name

# LANGKAH 2.4: Klik tombol "Create"

Kode di atas menunjukkan dua metode untuk membuat database. Pilih metode yang paling nyaman untuk Anda:

3b. Edit file .env

File .env adalah file konfigurasi environment Laravel. Bayangkan file ini seperti "kartu identitas aplikasi" yang berisi nama, alamat (URL), dan kredensial untuk mengakses berbagai layanan.

File ini tidak di-commit ke Git karena berisi credential sensitif seperti password database. Setiap developer bisa memiliki file .env berbeda sesuai environment masing-masing. Laravel menyediakan file .env.example sebagai template.

# ========================================
# KONFIGURASI APLIKASI
# ========================================

# LANGKAH 1: Nama dan environment aplikasi
APP_NAME="HRIS Modern"           # Nama yang tampil di browser tab
APP_ENV=local                     # Environment: local, staging, production
APP_KEY=                          # Akan di-generate otomatis
APP_DEBUG=true                    # True untuk development (tampilkan error detail)
APP_URL=http://localhost:8001     # URL aplikasi (port 8001 agar tidak bentrok)

# ========================================
# LOKALISASI
# ========================================

# LANGKAH 2: Setting bahasa dan locale
APP_LOCALE=id                     # Bahasa default: Indonesia
APP_FALLBACK_LOCALE=en            # Bahasa fallback jika terjemahan tidak ada
APP_FAKER_LOCALE=id_ID            # Faker generate data dummy Indonesia

# ========================================
# DATABASE
# ========================================

# LANGKAH 3: Konfigurasi koneksi database
DB_CONNECTION=mysql               # Driver database (mysql, pgsql, sqlite)
DB_HOST=127.0.0.1                 # Host database (localhost)
DB_PORT=3306                      # Port MySQL default
DB_DATABASE=hris_app              # Nama database yang sudah dibuat
DB_USERNAME=root                  # Username MySQL
DB_PASSWORD=                      # Password MySQL (kosong untuk XAMPP default)

# ========================================
# SESSION & CACHE
# ========================================

# LANGKAH 4: Driver penyimpanan session dan cache
SESSION_DRIVER=database           # Session disimpan di database
SESSION_LIFETIME=120              # Session expired setelah 120 menit

QUEUE_CONNECTION=database         # Queue job disimpan di database
CACHE_STORE=database              # Cache disimpan di database

# ========================================
# VITE
# ========================================

# LANGKAH 5: Konfigurasi untuk bundler Vite
VITE_APP_NAME="${APP_NAME}"       # Nama app untuk JavaScript

Kode di atas adalah konfigurasi lengkap untuk file .env. Perhatikan bahwa APP_KEY dibiarkan kosong - kita akan generate nilainya di step berikutnya.

Step 4: Generate Key dan Migrate

Setelah konfigurasi .env selesai, ada dua hal yang harus dilakukan: generate application key untuk enkripsi dan menjalankan migration untuk membuat tabel-tabel database. Bayangkan application key seperti "kunci brankas" yang digunakan untuk mengamankan data sensitif.

Application key adalah string random 32 karakter yang digunakan Laravel untuk mengenkripsi session, cookie, dan data sensitif lainnya. Tanpa key ini, aplikasi tidak bisa berjalan dengan aman. Setiap instalasi Laravel WAJIB memiliki key unik.

Migration adalah cara Laravel mengelola skema database. Daripada membuat tabel secara manual di phpMyAdmin, kita membuat file migration PHP yang mendefinisikan struktur tabel. Ini seperti "blueprint rumah" - setiap developer menggunakan blueprint yang sama sehingga hasilnya konsisten.

Keuntungan menggunakan migration: mudah rollback jika ada kesalahan, bisa di-track perubahannya di Git, dan otomatis sinkron antar developer. Semua perubahan database tercatat dalam kode, bukan dikerjakan manual.

# ========================================
# LANGKAH 1: GENERATE APPLICATION KEY
# ========================================

# LANGKAH 1.1: Generate random 32-character key
# Key ini akan otomatis diisi ke APP_KEY di file .env
# Digunakan untuk enkripsi session, cookie, password reset, dll
php artisan key:generate

# ========================================
# LANGKAH 2: JALANKAN MIGRATION
# ========================================

# LANGKAH 2.1: Buat tabel-tabel database
# Migration membaca file di database/migrations/
# dan membuat tabel sesuai definisi di masing-masing file
php artisan migrate

Kode di atas menjalankan dua command penting. Setelah migrate selesai, database hris_app akan terisi tabel-tabel default Laravel.

Step 5: Install Package Tambahan

Setelah setup dasar selesai, kita perlu menambahkan beberapa package yang akan digunakan di fitur-fitur HRIS. Package ini tidak wajib diinstall sekarang - Anda bisa install nanti saat dibutuhkan. Tapi lebih baik install sekarang agar tidak perlu bolak-balik.

5a. Backend Packages

# ========== INSTALL SPATIE PERMISSION ==========
# Package untuk mengelola role (Admin, HR, Employee) dan permission
composer require spatie/laravel-permission

# ========== PUBLISH CONFIG ==========
# Copy file konfigurasi ke folder config/
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"

# ========== MIGRATE PERMISSION TABLES ==========
# Buat tabel roles, permissions, model_has_roles, dll
php artisan migrate

5b. Frontend Packages

# ========== ICONS ==========
# Lucide - library icon modern (pengganti Font Awesome)
# Digunakan untuk icon di button, menu, dll
npm install lucide-react

# ========== DATE UTILITIES ==========
# date-fns - library untuk format dan manipulasi tanggal
# Digunakan untuk format "1 Januari 2025", "2 hari yang lalu", dll
npm install date-fns

# ========== CHARTS ==========
# Recharts - library chart berbasis React
# Digunakan untuk grafik di dashboard dan reports
npm install recharts

# ========== MAPS ==========
# Leaflet - library peta interaktif
# Digunakan untuk geofencing (validasi lokasi absensi)
npm install leaflet react-leaflet @types/leaflet

Step 6: Jalankan Development Server

Buka 2 terminal terpisah:

Step 7: Verifikasi Instalasi

FAQ - Pertanyaan yang Sering Diajukan

Troubleshooting

Struktur Folder Setelah Instalasi

HRISApp/
├── app/                    # Backend Laravel
│   ├── Http/
│   │   ├── Controllers/    # Controller files
│   │   └── Middleware/     # HandleInertiaRequests.php
│   └── Models/             # Eloquent models
├── database/
│   ├── migrations/         # Database migrations
│   └── seeders/            # Data seeders
├── resources/
│   ├── js/                 # Frontend React
│   │   ├── Components/     # Reusable components
│   │   ├── Layouts/        # Layout components
│   │   ├── Pages/          # Page components (Inertia)
│   │   └── app.tsx         # React entry point
│   └── css/
│       └── app.css         # Tailwind CSS
├── routes/
│   └── web.php             # Laravel routes
├── .env                    # Environment config
├── composer.json           # PHP dependencies
├── package.json            # NPM dependencies
├── tailwind.config.js      # Tailwind config
├── tsconfig.json           # TypeScript config
└── vite.config.js          # Vite config

Checkpoint - Verifikasi Instalasi

Sebelum melanjutkan ke lesson berikutnya, pastikan semua komponen terinstall dengan benar. Berikut adalah langkah-langkah verifikasi yang harus Anda lakukan:

Ringkasan