Registry Icon

resources/js/panel/icons/registry.ts adalah build-time allowlist yang mengubah nama icon dari server menjadi Vue component. File ini dihasilkan oleh php artisan panel:icons, disimpan di repository, lalu di-compile ke dalam bundle. Karena itu registry icon lebih tepat dianggap sebagai concern CI, bukan langkah deploy. Gunakan halaman ini ketika menambahkan pemeriksaan icon ke pipeline, atau ketika tombol di production tampil tanpa icon.

Contoh minimal yang berfungsi

Di CI, setelah npm dependency ter-install:

npm ci
php artisan panel:icons --check

INFO  The icon registry is up to date.

Di local development, setiap kali menambahkan ->icon('…') baru:

php artisan panel:icons
npm run build
git add resources/js/panel/icons/registry.ts

Mengapa registry icon merupakan concern deployment

Di sisi PHP, nama icon hanyalah string:

use PandaPanel\Actions\Action;

Action::make('approve')->icon('circle-check');

Nama tersebut hanya di-resolve melalui registry. Jika nama tidak menjadi key di registry, frontend merender tidak ada apa pun — tidak ada exception, placeholder, atau production console message:

export function resolveIcon(name: string | null | undefined): Component | null {
    if (typeof name !== 'string') {
        return null;
    }

    if (!isPanelIconName(name)) {
        // development only: one warning per unknown name
        return null;
    }

    return ICONS[name];
}

Failure mode registry yang stale adalah Panel tetap hidup tetapi beberapa tombol kehilangan icon, sementara server log terlihat bersih. Karena itu masalah harus ditemukan sebelum release, yaitu di CI.

Posisi command di pipeline

Tahap	Command	Alasan
CI	npm ci lalu php artisan panel:icons --check	pemeriksaan membutuhkan Lucide yang benar-benar ter-install pada disk
Local development	php artisan panel:icons	command menulis tracked file yang harus dicommit
Deploy	tidak ada	registry sudah ada di repository dan akan di-compile oleh npm run build

Jangan menjalankan panel:icons saat deploy.

Command menulis ke resources/js. Pada release-directory deployment, file tersebut adalah bagian dari artefact release yang sebentar lagi diganti, sehingga perubahan tidak pernah kembali ke repository. Command juga membutuhkan node_modules, yang belum tentu tersedia pada PHP-only deploy stage.

Contoh CI:

- run: npm ci
- run: php artisan panel:icons --check
- run: npm run build

npm ci harus lebih dulu agar command dapat memeriksa nama terhadap Lucide. Jika Lucide belum tersedia:

WARN  @lucide/vue is not installed; nothing to check names against.

Dalam kondisi itu seluruh nama dianggap valid. Menganggap semuanya invalid justru akan mengosongkan registry dan menyebabkan seluruh icon hilang hanya karena seseorang menjalankan command sebelum npm install.

Command

php artisan panel:icons
php artisan panel:icons --check

panel:icons
    {--check : Fail instead of writing, for CI}

Option	Default	Efek
--check	off	tidak menulis file; membandingkan output yang seharusnya dihasilkan dengan file yang ada, lalu gagal jika berbeda

Exit code

Run	Hasil	Code
default	file ditulis, semua nama dikenal Lucide	0
default	file ditulis, satu atau lebih nama bukan icon Lucide	1
--check	file sama dan semua nama valid	0
--check	file sama tetapi ada nama invalid	1
--check	file berbeda	1

Run default tetap menulis known icon walaupun menemukan typo. Exit non-zero hanya menunjukkan terdapat nama bermasalah:

ERROR  Not a Lucide icon: trahs, user-circle-2

Pesan tersebut adalah satu-satunya warning eksplisit yang diberikan untuk typo nama icon. Di runtime, icon invalid hanya tidak tampil.

Source yang dibaca command

Command memindai file .php dari dua root:

Root	Alasan
app_path()	panel, resource, page, widget, action milik application
src/ milik package	banyak icon berasal dari built-in action seperti delete, edit, export; jika hanya scan app/, built-in icon akan hilang dari registry

Nama dibaca langsung dari source code, bukan dari Panel yang sudah di-boot. Alasannya beberapa icon dapat berada pada declaration yang tidak pernah dijangkau oleh satu runtime walk, misalnya:

• wizard step;
• filter tab;
• header action;
• action yang dibuat di dalam method tertentu.

Command mengenali lima bentuk literal declaration serta body dari method yang benar-benar bernama:

icon(): string

Daftar nama icon yang tersedia dibaca dari:

node_modules/@lucide/vue/dist/esm/icons/*.mjs

Artinya validation menggunakan icon yang benar-benar tersedia pada versi Lucide yang ter-install, bukan daftar hard-coded di PHP.

File yang ditulis

Destination ditentukan melalui:

PandaPanel\Support\FrontendPaths::panel('icons/registry.ts')

Sehingga application yang memindahkan frontend Panel melalui frontend.panel_path tetap mendapatkan registry pada lokasi yang benar.

use PandaPanel\Support\FrontendPaths;

FrontendPaths::panel('icons/registry.ts');
// '/app/resources/js/panel/icons/registry.ts'

Nama icon diurutkan sehingga output byte-stable lintas run dan machine. Stabilitas inilah yang membuat --check dapat membandingkan file secara bermakna tanpa noise karena perbedaan urutan.

Memverifikasi lewat test

Test suite package memastikan registry dapat me-resolve seluruh icon yang diminta source, termasuk built-in icon dari framework. Application dapat menambahkan test serupa:

it('keeps the registry in step with the icons the source declares', function (): void {
    $this->artisan('panel:icons --check')->assertSuccessful();
});

Runtime walk terhadap navigation/table action menemukan sebagian besar icon. panel:icons melengkapi sisanya karena membaca source, bukan hanya object yang terbangun saat boot.

Bundle size

Lucide memiliki ribuan icon, tetapi PandaBear biasanya hanya menggunakan beberapa puluh. Registry berisi static object dengan named imports sehingga icon yang tidak digunakan dapat di-tree-shake oleh bundler.

Jadi generator registry mengubah siapa yang menjaga daftar, bukan mengubah guarantee bundle.

Ini juga alasan registry tidak menggunakan dynamic import berdasarkan arbitrary runtime string. Runtime string dari server tidak boleh dapat menunjuk langsung ke module arbitrary pada bundle, dan dynamic import seperti itu juga tidak dapat dianalisis secara statis dengan baik.

Hal yang perlu diperhatikan

• Registry merupakan build artifact yang memang dicommit. Perubahan hasil generate adalah tracked diff, dan itulah yang membuat --check berguna.
• Regenerate belum cukup. Karena file TypeScript ikut di-compile, jalankan npm run build setelah registry berubah.
• Nama harus lowercase kebab-case literal. Contoh 'ArrowRight' tidak cocok. Nama icon yang disimpan dalam constant atau dibangun melalui concatenation tidak terdeteksi scanner.
• Package plugin lain di vendor/ tidak ikut discan. Jika plugin eksternal mendeklarasikan icon di src/ miliknya, expose nama tersebut melalui source di app/ atau published component plugin.
• Unknown icon di production hanya tidak tampil. Warning hanya aktif pada import.meta.env.DEV karena ini adalah build problem, bukan runtime incident.
• Menjalankan generator saat deploy menulis file yang tidak akan pernah dicommit. Generate di development, validasi di CI.

Lihat juga

• Production checklist, Frontend build
• panel:icons — seluruh pattern yang dikenali scanner
• Icons — cara nama icon menjadi component
• Icons troubleshooting
• Component registries
• Frontend paths
• CI matrix