Development Lokal

Halaman ini menjelaskan cara membawa checkout chocoalano/panel sampai seluruh verification loop dapat dijalankan. Package terdiri dari dua bagian yang diperiksa oleh toolchain berbeda — PHP di src/, serta Vue dan TypeScript di resources/js/. Keduanya tidak dapat memvalidasi sisi lain, jadi setup development yang benar berarti kedua toolchain harus berfungsi.

Contoh minimal

git clone https://github.com/chocoalano/panda-panel.git
cd panda-panel

composer install
npm ci

composer ci     # pint --test, lalu phpstan, lalu pest
npm run ci      # prettier --check, lalu eslint, lalu vue-tsc, lalu vite build

Kedua script dideklarasikan langsung di repository dan sama dengan yang dijalankan CI. Jika perubahan lolos lokal tetapi gagal di CI, penyebabnya biasanya version-specific: kombinasi PHP/Laravel/Node atau --prefer-lowest. Lihat CI matrix.

Tidak ada .env yang perlu dibuat, database server yang perlu dijalankan, atau php artisan step. Test suite menggunakan sqlite :memory: dan membangun application sendiri.

Isi sebuah checkout

src/            framework — PandaPanel\*, PSR-4 dari composer.json
config/         config/panda-panel.php
database/       migration milik package
stubs/          scaffold generator untuk make:panel*
resources/      css, js — frontend Vue yang dipublish ke application
examples/       application yang digunakan test suite
tests/          test suite
frontend/       host stand-in dan compile-check entry
docs/           dokumentasi ini
build/          scratch output — gitignored

Lima directory pertama adalah surface package yang dikirim. Sisanya digunakan untuk development dan di-export-ignore melalui .gitattributes, sehingga composer require chocoalano/panel tidak mengirimkannya ke application. Lihat Releases untuk daftar lengkapnya dan satu file yang tampak development-only tetapi sengaja tetap didistribusikan.

Dua toolchain

PHP

composer.json menyediakan enam script yang menjadi entry point utama development PHP:

Script	Menjalankan
composer test	vendor/bin/pest
composer test-coverage	vendor/bin/pest --coverage
composer format	vendor/bin/pint
composer format-check	vendor/bin/pint --test
composer analyse	vendor/bin/phpstan analyse --memory-limit=1G
composer ci	@format-check, lalu @analyse, lalu @test

composer format          # memperbaiki style
composer analyse         # Larastan level 4 untuk src dan database
composer test            # seluruh suite
composer ci              # semua check, dengan urutan error paling berguna

Urutan composer ci sengaja dibuat dari failure termurah untuk diperbaiki ke yang membutuhkan investigasi lebih banyak: style biasanya satu command fix, static analysis menunjuk line, sedangkan test failure perlu membaca behavior. Tidak masuk akal menunggu satu menit test hanya untuk menemukan declare(strict_types=1) hilang.

Frontend

package.json menyediakan tujuh script:

Script	Menjalankan
npm run lint	eslint resources/js frontend --max-warnings=0
npm run lint:fix	eslint resources/js frontend --fix
npm run format	prettier --write resources/js frontend resources/css
npm run format:check	prettier --check resources/js frontend resources/css
npm run typecheck	vue-tsc --noEmit -p tsconfig.json
npm run build	vite build
npm run ci	format:check, lint, typecheck, build

npm ci                   # install dari committed lockfile
npm run format           # memperbaiki formatting
npm run lint:fix         # memperbaiki lint yang auto-fixable
npm run typecheck        # vue-tsc pada seluruh component
npm run build            # compile seluruh tree
npm run ci               # semua frontend check seperti CI

engines menetapkan "node": ">=20.19". CI menguji Node 20, 22, dan 24. Versi lebih lama tidak didukung dan dependency seperti @tailwindcss/vite serta Vite 7 tidak dijamin resolve.

npm run build tidak menghasilkan artifact distribusi. Fungsinya adalah membuktikan seluruh file benar-benar resolve dan compile bersama. Lihat Frontend toolchain.

Test application

Package tidak memiliki bootstrap/app.php sendiri. Test suite membangun application melalui orchestra/testbench dan menunjuknya ke examples/:

// tests/TestCase.php

protected function resolveApplicationConfiguration($app): void
{
    $app->useAppPath((string) realpath(__DIR__.'/../examples/app'));
    $app->useDatabasePath((string) realpath(__DIR__.'/../examples/database'));
    $app->useBootstrapPath((string) realpath(__DIR__.'/../vendor/orchestra/testbench-core/laravel/bootstrap'));
    $app->useStoragePath(dirname(__DIR__).'/build/testbench/storage');

    parent::resolveApplicationConfiguration($app);
}

examples/ berisi App\Models\User, App\Panels\Admin, App\Panels\App, policy, factory, route, dan Inertia root view. Namespace App\ didaftarkan melalui autoload-dev, sehingga hanya tersedia saat development dan tidak ikut package. Menjadikan example application sebagai test application memastikan contoh nyata terus dieksekusi dan tidak membusuk sebagai dokumentasi pasif.

applicationBasePath() membuat base_path() dan resource_path() menunjuk ke package root karena icon registry, generator stubs, dan TypeScript yang dipakai untuk memvalidasi serialized schema benar-benar berada di repository ini.

Directory yang dibuat saat test berjalan

Git tidak dapat menyimpan empty directory. Daripada menambahkan banyak .gitkeep, TestCase::prepareWritableDirectories() membuat directory yang dibutuhkan saat pertama kali test berjalan. Method dipanggil dari tests/Pest.php sebelum application pertama dibangun:

bootstrap/cache                          Laravel package manifest
resources/views                          dipakai view finder glob
build/testbench/storage/app/private      tempat export disimpan
build/testbench/storage/framework/views
build/testbench/storage/framework/cache/data
build/testbench/storage/framework/sessions
build/testbench/storage/logs

Dua directory pertama harus berada di bawah base path, bukan build/, karena Laravel menulis package manifest saat application masih dibangun dan route:cache dapat merebuild application dalam process yang tidak melihat TestCase. Keduanya tidak ikut distribusi dan di-gitignore.

Bersihkan semuanya dengan:

rm -rf build bootstrap resources/views

build/ juga berisi build/phpstan dan build/frontend. Menghapusnya hanya membuat run berikutnya sedikit lebih lambat.

Menjalankan sebagian check

Pest menerima path, filter, atau keduanya:

vendor/bin/pest tests/Feature/Panel/ResourceQueryTest.php
vendor/bin/pest --filter=ResourceUrl
vendor/bin/pest --filter='refuses a member the index'
vendor/bin/pest --compact                 # satu karakter per test
vendor/bin/pest --bail                    # berhenti pada failure pertama
vendor/bin/pest --dirty                   # hanya file dengan perubahan lokal
vendor/bin/pest --coverage                # membutuhkan Xdebug atau PCOV

Pint dapat menerima path dan beberapa mode:

vendor/bin/pint                    # fix semua file yang tidak dikecualikan
vendor/bin/pint src tests          # fix path tertentu
vendor/bin/pint --test             # report tanpa mengubah — seperti CI
vendor/bin/pint --dirty            # file dengan perubahan lokal saja
vendor/bin/pint --diff=main        # file yang berubah sejak branch dari main
vendor/bin/pint -v                 # tampilkan rule yang terpicu

PHPStan membaca phpstan.neon dari repository root:

vendor/bin/phpstan analyse
vendor/bin/phpstan analyse --memory-limit=1G      # yang dipanggil composer analyse
vendor/bin/phpstan analyse --no-progress          # yang dipanggil CI
rm -rf build/phpstan                              # hapus result cache

Frontend scripts tidak menerima argument tambahan, tetapi underlying tools dapat dipanggil langsung:

npx eslint resources/js/panel/tables --max-warnings=0
npx prettier --check resources/js/panel/forms
npx vue-tsc --noEmit -p tsconfig.json

Menjalankan Artisan command dalam development package

Repository ini tidak memiliki binary artisan karena bukan Laravel application. Command diuji di dalam Testbench application, sama seperti suite menjalankannya:

it('creates a panel provider and the directories discovery scans', function (): void {
    $this->artisan('make:panel', ['name' => 'Testing'])->assertSuccessful();

    expect(File::exists(app_path('Panels/Testing/TestingPanelProvider.php')))->toBeTrue();
});

app_path() pada test mengarah ke examples/app, sehingga generator menulis ke example application dan GeneratorTest menghapus hasilnya setelah selesai. examples/app/Panels/Testing di-gitignore untuk alasan tersebut.

GeneratorTest kemudian menjalankan Pint pada generated code agar stub yang drift dari coding standard gagal di repository ini, bukan baru gagal di project pengguna:

$pint = Process::run([base_path('vendor/bin/pint'), '--test', app_path('Panels/Testing')]);

expect($pint->successful())->toBeTrue($pint->output());

Test ini skip jika vendor/bin/pint tidak tersedia, sehingga install --no-dev tidak gagal hanya karena dev tool tidak ada.

Apa yang di-track Git

Beberapa entry .gitignore sering mengejutkan:

composer.lock
.github
.ai
.claude
.codex

• composer.lock tidak di-commit. Library harus bekerja terhadap version range di composer.json, bukan satu resolution tertentu. CI selalu melakukan fresh resolve, termasuk --prefer-lowest dan --prefer-stable. Karena itu composer install pada clone baru melakukan resolve dan dapat menghasilkan patch version berbeda antar-checkout.
• package-lock.json justru di-commit. Toolchain repository perlu reproducible, sehingga CI memakai npm ci. Application pengguna hanya melihat version ranges dan tidak pernah menerima lockfile repository ini.
• .github/ di-ignore. Workflow file ada pada working tree tetapi tidak otomatis tracked; perubahan harus menggunakan git add -f .github/workflows/tests.yml.

Catatan

• composer install pada fresh clone menampilkan "No lock file found" lalu melakukan resolve. Itu kondisi yang diharapkan.
• Suite membutuhkan pdo_sqlite dan zip. sqlite dipakai untuk :memory: dan zip dipakai XLSX writer yang benar-benar dijalankan, bukan mock.
• PHP test tidak bergantung pada npm run build. Illuminate\Foundation\Vite diganti dengan Tests\Fixtures\Panel\FakeVite, jadi seluruh PHP suite tetap dapat berjalan tanpa node_modules.
• Fixture Panel harus dicek dengan PanelManager::has() sebelum registrasi. Registry dapat bertahan antar-test dalam process yang sama dan duplicate registration melempar exception.
• vendor/bin/pest --coverage membutuhkan coverage driver. CI menggunakan coverage: none, jadi coverage adalah tool lokal.
• Menghapus build/ juga menghapus Testbench storage. Suite akan membuatnya kembali dan tidak ada data penting yang perlu dipertahankan.

Lihat juga

• Running the tests — harness, fixture, dan tempat test baru ditulis
• Frontend toolchain — fungsi setiap config frontend
• Coding standards — aturan Pint/PHPStan dan jebakannya
• Pull requests — checklist sebelum membuka PR
• Releases — versioning, changelog, dan export list
• CI matrix — bagaimana semua command digabungkan di GitHub Actions
• Directory structure — tree yang sama dari sisi application
• Test setup — helper untuk testing Panel di project pengguna