3 · Memasang PandaBear

Tujuan: panel terdaftar di /admin, frontend yang berhasil di-build, plus kemampuan membaca laporan installer — keterampilan paling berguna di seluruh tutorial ini.

Lakukan ini

composer require chocoalano/panel
php artisan panel:install
npm install
npm run build

Itu seluruh proses instalasinya. Sisa halaman ini menjelaskan apa yang dikerjakan tiap bagian, karena kalau nanti ada yang salah, jawabannya biasanya ada di sini.

Apa yang dilakukan composer require sendiri

Paketnya mendeklarasikan service provider dan facade-nya, sehingga package discovery Laravel menyambungkan keduanya tanpa suntingan dari Anda:

"extra": {
    "laravel": {
        "providers": ["PandaPanel\\PandaPanelServiceProvider"],
        "aliases": { "PandaPanel": "PandaPanel\\Facades\\PandaPanel" }
    }
}

Saat boot, service provider mendaftarkan binding container, panel-panel yang disebut di config/panda-panel.php (belum ada), empat alias middleware, guest redirect, grup route, migrasi paket, tag publish, dan perintah artisan.

Belum ada panel, jadi belum ada URL yang menjawab. Itulah tugas perintah berikutnya.

Apa yang dilakukan panel:install, langkah demi langkah

Enam langkah, dengan urutan ini. Setiap langkah tersedia secara terpisah — vendor:publish per tag, make:panel, panel:user — jadi tidak ada satu pun yang tidak bisa Anda ulangi atau kerjakan manual.

1. Publikasi config dan frontend

php artisan vendor:publish --tag=panda-panel-config    # config/panda-panel.php
php artisan vendor:publish --tag=panda-panel-assets    # komponen Vue

Tujuh sumber disalin ke aplikasi Anda:

Dari paket	Ke aplikasi Anda
resources/js/panel	resources/js/panel
resources/js/components	resources/js/components
resources/js/composables	resources/js/composables
resources/js/lib	resources/js/lib
resources/js/pages	resources/js/pages
resources/js/types	resources/js/types
resources/css/panda-panel.css	resources/css/panda-panel.css

Frontend-nya dipublikasikan, bukan diimpor dari vendor, karena setiap registry komponen adalah allowlist import.meta.glob atas pohon berkas Anda sendiri: komponen yang tidak pernah dilihat proses build adalah komponen yang tidak bisa di-resolve. Berkas-berkas ini kini milik Anda — ada di repositori Anda, ikut di-build, dan boleh disunting.

vendor:publish tidak pernah menimpa berkas yang sudah ada tanpa --force, jadi resources/js/components/* bawaan starter kit tetap utuh.

Setelah itu installer menulis .panel-assets.json, yang mencatat rupa setiap berkas saat dipublikasikan. Commit berkas itu. Tanpanya, proses upgrade tidak bisa membedakan hasil suntingan Anda dari salinan yang tertinggal versi.

2. Scaffold panelnya

php artisan make:panel Admin

app/Panels/Admin/
├── AdminPanelProvider.php
├── Pages/.gitkeep
├── Resources/.gitkeep
└── Widgets/.gitkeep

Berkas .gitkeep bukan hiasan — discovery memindai direktori itu, sementara Git tidak melacak direktori kosong, jadi tanpanya provider akan menunjuk ke path yang lenyap begitu proyek di-clone.

Berikut provider yang dihasilkan. Bacalah baris per baris, karena Anda akan menyuntingnya di langkah 8:

<?php

declare(strict_types=1);

namespace App\Panels\Admin;

use PandaPanel\Core\Panel;
use PandaPanel\Core\PanelProvider;

final class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->path('admin')                                          // prefix URL
            ->name('Admin')                                          // nama tampilan
            ->icon('layout-grid')                                    // key ikon Lucide
            ->auth()                                                 // menambah middleware auth + verified
            ->discoverResources(app_path('Panels/Admin/Resources'))  // dipindai untuk kelas Resource
            ->discoverPages(app_path('Panels/Admin/Pages'))
            ->discoverWidgets(app_path('Panels/Admin/Widgets'));
    }
}

Id panel diturunkan dari nama kelasnya: AdminPanelProvider → admin. Id itulah yang dirujuk setiap nama route, setiap opsi --panel=, dan setiap parameter middleware.

3. Daftarkan di config

Langkah inilah yang membuat URL-nya menjawab:

// config/panda-panel.php
'panels' => [
    App\Panels\Admin\AdminPanelProvider::class,
],

Panel didaftarkan, bukan ditemukan otomatis, karena dua alasan: application mendeklarasikan seluruh panelnya di satu tempat, dan menambah panel seharusnya merupakan suntingan yang disengaja — bukan efek samping dari isi direktori. Ketika request tidak menyebut panel tertentu, PandaBear berjalan berdasarkan id panel, bukan urutan config. Kelas-kelas di dalam panel tetap ditemukan otomatis.

Installer menyunting berkas itu secara tekstual — baris yang sama, di tempat yang sama, seperti yang akan Anda tulis sendiri — karena isi config sebagian besar adalah komentar penjelas tiap kunci, dan menulis ulang dari array hasil parsing akan membuang semuanya. Ada empat kemungkinan hasil:

Hasil	Artinya
registered	Barisnya ditulis, atau placeholder berkomentar bawaan paket dibuka komentarnya
already-present	Entri aktif sudah ada; tidak ada yang ditulis
no-config	config/panda-panel.php tidak ada — tambahkan barisnya sendiri
unrecognised	Array panels tidak berbentuk seperti bawaan paket. Berkas dibiarkan apa adanya

Ini penyebab "kok tidak jalan" yang paling sering

Tanpa baris ini instalasi tetap selesai, provider tetap ada, dan /admin mengembalikan 404. Kalau Anda melihat 404, periksa array ini lebih dulu.

4. Laporan soal home redirect

Signed-in visitors to /dashboard now land in the panel. Set home_redirect.enabled to false
in config/panda-panel.php to keep your own.

Dicetak, bukan ditanyakan. Ini satu-satunya hal yang berubah dari layar yang sudah dimiliki aplikasi Anda — dan redirect yang tidak diberitahukan kepada siapa pun akan berakhir menjadi laporan bug. Route Anda, namanya, dan pages/Dashboard.vue tidak disentuh; request-nya hanya dijawab lebih awal oleh sebuah middleware.

5. Periksa frontend

Enam pemeriksaan yang sifatnya hanya membaca: Inertia, Vite, manifest dependensi, paket npm, penetapan layout dari langkah 2, dan modul host @/…. Setiap kegagalan masuk ke daftar pekerjaan tersisa, bukan dicetak di tempat kejadian.

6. Tawaran membuat user

Create a user who can sign in? (yes/no) [no]

Ditawarkan, bukan diasumsikan — membuat baris di tabel user milik orang lain tanpa diminta bukan tugas sebuah installer. Jawab no dulu; langkah 4 membahas perintah ini dengan benar.

Membaca laporannya

Ada dua kemungkinan akhir. Yang menyenangkan:

Done. Nothing is left to do by hand.

Dan yang berguna:

WARN  2 thing(s) this package cannot do for your application:

  1. Install the npm dependencies the components import, then rebuild:
     npm install @tanstack/vue-table@^9.0.0 vue-sonner@^2.0.0
     npm run build
  2. resources/js/app.ts line 12 overwrites the layout every panel page declares:
     page.default.layout = AppLayout;
     Use ??= or ||= instead.

Semua isi daftar itu bisa langsung disalin-tempel. Baris npm install hanya menyebut paket yang proyek Anda memang belum punya, dibaca dari package.json milik paketnya — jadi daftarnya tidak mungkin basi terhadap apa yang benar-benar diimpor komponen.

Exit code-nya selalu 0

Pekerjaan tersisa dilaporkan sebagai pekerjaan, bukan sebagai kegagalan. Shell yang menganggap "Anda masih perlu menjalankan npm install" sebagai build gagal akan menghentikan deploy Anda untuk alasan yang keliru. Kalau Anda membuat skrip di sekitar perintah ini, periksa keluarannya, bukan status exit-nya.

Build frontend-nya

npm install
npm run build

Memasang bukan berarti mem-build. Komponen panel adalah Vue; npm run build — atau npm run dev selama Anda bekerja — yang mengubahnya menjadi sesuatu yang bisa dimuat browser. URL panel yang tampil sebagai HTML tanpa gaya hampir selalu berarti build belum dijalankan.

Pastikan berhasil

php artisan route:list --name=panel.

Anda semestinya melihat panel.admin.dashboard di /admin, ditambah route action, notifikasi, pencarian, dan pengaturan milik panel. Lalu:

php artisan panel:cache    # discovery sekali, dilaporkan sebagai jumlah
php artisan panel:clear    # kembali ke discovery per request

panel:cache mencetak berapa panel, resource, page, dan widget yang ditemukan. Saat ini jumlahnya satu panel dan nol untuk sisanya — itu benar, dan itulah angka pembanding setelah langkah 5.

Kalau gagal

Gejala	Penyebab	Perbaikan
composer require menolak	Ada batasan dari langkah 1 yang belum terpenuhi	Baca pesan composer — nama paket dan versinya disebutkan
/admin menghasilkan 404	Provider belum ada di panels	Tambahkan barisnya di config/panda-panel.php
/admin tampil sebagai HTML polos	Frontend belum pernah di-build	npm run build
Semua layar panel 500	Root view atau middleware Inertia tidak ada	php artisan inertia:middleware
Layar panel dirender di dalam sidebar aplikasi Anda	Penetapan layout di app.ts	Ubah = menjadi ??=

Berikutnya

Panelnya sudah ada. Belum ada yang bisa masuk ke dalamnya.

→ 4 · Akun pertama dan login

Baca juga

• Installation — langkah yang sama, dikerjakan manual
• Running panel:install — setiap opsi dan setiap kemungkinan hasil
• Common install problems
• Publish tags