Setup Laravel Vue Starter Kit

Published component milik Panel mengimpor sembilan belas module yang tidak dikirim package, dan aplikasi Laravel Vue starter kit sudah memiliki semuanya. Itulah seluruh arti dari "starter kit assumption": jika PandaBear dipasang ke starter kit, frontend langsung memiliki dependency host yang dibutuhkan; jika dipasang ke aplikasi selain starter kit, sembilan belas module tersebut menjadi pekerjaan yang harus disediakan aplikasi. Dokumen ini menunjukkan jalur tercepat dari aplikasi starter kit baru sampai Panel yang bekerja, beserta perubahan yang terlibat.

Dari Aplikasi Kosong sampai Panel

laravel new acme            # choose the Vue starter kit when prompted
cd acme
php artisan migrate

composer require chocoalano/panel
php artisan panel:install

npm install
npm run build
php artisan serve

panel:install seharusnya selesai dengan pesan Done. Nothing is left to do by hand.. Setelah sign-in, user masuk ke Panel pada /admin, bukan ke placeholder dashboard milik starter kit.

Apa yang Sudah Disediakan Starter Kit

PandaBear tidak membaca atau mengedit file-file berikut. Package hanya mengimpornya; itulah seluruh hubungan antara Panel dan starter kit.

	Digunakan Panel untuk
resources/views/app.blade.php	Root view Inertia. Tanpanya setiap URL Panel menghasilkan HTTP 500.
app/Http/Middleware/HandleInertiaRequests.php	Middleware Inertia. Panel membagikan prop miliknya secara terpisah melalui SharePanelData.
resources/js/app.ts	Entry Inertia. Panel membutuhkannya agar tidak menimpa layout yang sudah dideklarasikan setiap Page.
vite.config.ts	Frontend build, sekaligus tempat Wayfinder plugin berjalan.
resources/css/app.css	Tailwind 4 theme yang menjadi sumber utility styling Panel.
@/components/*, @/composables/useTwoFactorAuth, @/types, @/types/ui	Account UI dan shared type yang diimpor Settings Page milik Panel.
@/routes/*, @/actions/*	Output Wayfinder yang dibuat dari route table aplikasi.
App\Providers\FortifyServiceProvider	Auth screen milik aplikasi sendiri, yang tetap berada pada tempat dan flow-nya.

Daftar specifier lengkap dan behavior ketika salah satunya hilang tersedia pada Frontend requirements.

Generate Module Wayfinder

Sembilan dari sembilan belas module dibuat dari route dan controller aplikasi sendiri — enam di bawah @/routes dan tiga di bawah @/actions:

php artisan wayfinder:generate

Vite config milik starter kit menjalankan plugin Wayfinder ketika build, sehingga npm run build juga meregenerasi module tersebut. panel:install melaporkan module generated secara terpisah dari component, karena diagnosisnya berbeda: jika seluruh @/routes/* dan @/actions/* hilang, Wayfinder belum berjalan; jika hanya beberapa component yang hilang, kemungkinan aplikasi bukan starter kit.

Satu Edit yang Sangat Mudah Salah

Setiap Page Panel mendeklarasikan layout sendiri:

defineOptions({ layout: PanelLayout });

Jika resources/js/app.ts menetapkan layout secara unconditional di Inertia resolver, assignment tersebut menimpa layout Page setelah Page memilihnya:

createInertiaApp({
    resolve: (name) => {
        const page = resolvePageComponent(`./pages/${name}.vue`, import.meta.glob('./pages/**/*.vue'));

        page.default.layout = AppLayout;      // wrong: every panel screen renders in your shell
        page.default.layout ??= AppLayout;    // right: a page that named its own layout keeps it

        return page;
    },
});

Versi yang salah menghasilkan HTTP 200, menampilkan sidebar aplikasi, tidak menampilkan Panel navigation, dan tidak menghasilkan log error. panel:install membaca file tersebut dan melaporkan line yang bermasalah. Check ini dilakukan otomatis karena failure-nya terlalu silent untuk hanya dijelaskan di dokumentasi.

Opsional: Mengeluarkan Vite Entrypoint Milik Panel

Hanya dibutuhkan jika Panel mendeklarasikan asset melalui Panel::assets(). Root view menambahkan entrypoint tersebut:

@vite([
    'resources/css/app.css',
    'resources/js/app.ts',
    "resources/js/pages/{$page['component']}.vue",
    ...(panel()?->getAssets() ?? []),
])

panel() mengembalikan current Panel atau null di luar Panel, sehingga spread tersebut kosong pada seluruh Page starter kit dan pada Panel yang tidak mendeklarasikan asset tambahan.

Bagian Starter Kit yang Diambil Alih Panel

Ada dua alamat yang berubah behavior. Route, nama route, dan Page component milik aplikasi tetap ada.

/dashboard

User yang sudah sign-in dan masuk ke alamat tersebut diarahkan ke Panel pertama yang dapat diakses. Behavior ini dilakukan melalui middleware web — PandaPanel\Http\Middleware\RedirectPanelHome — bukan melalui competing route. /dashboard adalah route milik aplikasi; package yang mendaftarkan route dengan URI sama akan bergantung pada registration order untuk "menang", dan itu bukan design yang aman.

// config/panda-panel.php
'home_redirect' => [
    'enabled' => true,
    'paths' => ['dashboard'],
],

Matikan enabled jika ingin mempertahankan Dashboard aplikasi. Value pada paths merupakan pattern Request::is(), sehingga 'reports/*' dapat menyerahkan satu section penuh. Path tempat Panel itu sendiri dipasang akan diabaikan; ini mencegah Panel pada /dashboard melakukan redirect ke dirinya sendiri tanpa akhir. Guest, non-GET request, dan request yang menginginkan JSON juga tidak diubah.

Guest Membuka URL Panel

Guest yang membuka URL Panel diarahkan ke Login Page milik Panel tersebut jika Panel menyediakannya, dan ke route('login') jika tidak. Fallback kedua merupakan behavior default Laravel, sehingga package menambahkan satu kasus baru tanpa mengganti fallback utama.

Service provider mendaftarkannya melalui:

// config/panda-panel.php
'register_guest_redirect' => true,

Set ke false jika bootstrap/app.php aplikasi sudah memanggil redirectGuestsTo() sendiri. Agar Panel Login tetap berfungsi, panggil rule package dari custom redirect Anda:

use PandaPanel\Support\PanelLoginRedirect;

->withMiddleware(function (Middleware $middleware): void {
    $middleware->redirectGuestsTo(
        fn ($request) => PanelLoginRedirect::for($request) ?? route('welcome'),
    );
})

/settings/*

Package tidak melakukan perubahan apa pun pada URL ini. Example application mengarahkan settings URL milik aplikasi ke Settings Page milik Panel agar bookmark dan Wayfinder link lama tetap dapat digunakan, sementara write route tetap berada pada aplikasi:

Route::middleware('auth')->group(function (): void {
    Route::get('settings/profile', [SettingsRedirectController::class, 'profile'])->name('profile.edit');

    // The screen moved into the panel; the write did not.
    Route::patch('settings/profile', [ProfileController::class, 'update'])->name('profile.update');
});

Copy behavior tersebut hanya jika memang diinginkan. Lihat examples/routes/web.php dan examples/app/Http/Controllers/Settings/SettingsRedirectController.php.

Fortify dan Dua Set Auth Screen

Starter kit menghubungkan Fortify view ke Inertia Page milik aplikasi sendiri. Biarkan konfigurasi tersebut tetap ada:

use Laravel\Fortify\Fortify;

Fortify::loginView(static fn () => Inertia::render('auth/Login'));
Fortify::createUsersUsing(CreateNewUser::class);

Panel yang mengaktifkan front door sendiri merender versi screen milik Panel pada path Panel dan dengan branding Panel:

$panel->auth()->login()->passwordReset()->emailVerification();

Kedua set screen tetap submit ke Fortify endpoint yang sama. Membuat login POST terpisah untuk setiap Panel berarti menduplikasi rate limiting, two-factor, passkeys, dan session handling — empat concern yang tidak boleh memiliki behavior berbeda hanya karena user masuk dari pintu berbeda.

auth() dan login() merupakan concern terpisah. auth(verified: true) menambahkan middleware auth dan verified ke Panel, sedangkan login() yang menyediakan guest auth routes milik Panel sendiri.

Jika Aplikasi Anda Bukan Starter Kit

Bagian server tidak bergantung pada starter kit. Yang perlu Anda sediakan adalah sembilan belas host module tersebut. Repository PandaBear memiliki minimal stand-in yang sudah typed dengan benar di frontend/host/. File tersebut digunakan hanya untuk type-check/build repository package sendiri, export-ignore sehingga tidak dibawa oleh composer require, tetapi dapat dibaca sebagai spesifikasi contract module yang harus Anda implementasikan.

Urutan implementasi yang bekerja:

1. Jalankan php artisan inertia:middleware, lalu sediakan root view pada resources/views/app.blade.php.
2. Buat vite.config.ts dengan plugin Vue dan Tailwind 4.
3. Jalankan npm install untuk package yang disebut panel:install.
4. Install dan jalankan Wayfinder untuk menghasilkan @/routes/* dan @/actions/*.
5. Buat tujuh component, satu composable, dan dua type module; atau salin implementation yang sesuai dari Laravel Vue starter kit.
6. Jalankan php artisan panel:install kembali. Installer akan memeriksa ulang semuanya dan idealnya tidak lagi melaporkan outstanding work.

Catatan

• Page component /dashboard milik starter kit tidak pernah dihapus. Mematikan home_redirect mengembalikan screen tersebut seperti semula.
• panel:install aman dijalankan ulang. Publish melewati file yang sudah ada, registration menjadi no-op untuk Panel yang sudah terdaftar, dan frontend check hanya membaca file.
• Upgrade starter kit dapat memperkenalkan kembali unconditional layout assignment. File tersebut milik aplikasi, sehingga panel:assets tidak dapat memberi tahu Anda. Jalankan panel:install atau check terkait setelah menerima update starter kit.
• Panel tidak membutuhkan AppLayout milik starter kit. PandaBear mengirim PanelLayout dan PanelBlankLayout, lalu setiap Page mendeklarasikannya sendiri. Starter kit shell hanya digunakan oleh Page milik starter kit.

Lihat Juga

• Frontend requirements — sembilan belas host module secara lengkap
• Installation dan Running panel:install
• Opening your first panel
• Frontend: host modules, Wayfinder
• Authentication: Fortify, login
• Configuration: home redirect, guest redirect
• Troubleshooting: login redirects, Inertia root view