Thumbnails Laravel Package

Getting Started

This package ships a control panel UI (compiled CSS/JS) inside a standard Laravel package. Start here:

1. Install and pin the fixed version. The 1.0.1 release corrects missing compiled control panel assets, so require ^1.0.1 rather than ^1.0.0 — earlier installs can render an unstyled or non-interactive panel.

   composer require vendor/package:^1.0.1
   

2. Publish what the package exposes. Check the service provider (or php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider") for config, migrations, views, and — critically for this release — public assets. Publish config first; it is the primary extension surface.

   php artisan vendor:publish --tag=package-config
   php artisan vendor:publish --tag=package-assets --force
   

3. Run migrations and clear caches if the package persists panel data or registers routes.

   php artisan migrate
   php artisan optimize:clear
   

4. Look first at: config/package.php (panel path, middleware, auth guard), the package's routes/ file, and public/vendor/package/ to confirm the CSS/JS bundles actually landed.

First use case: log in as an authorized user, hit the configured panel path (commonly /admin), and verify the panel loads with styles and working JS. If it renders bare HTML, you are almost certainly on a pre-1.0.1 install or missing published assets — see Gotchas.

Implementation Patterns

Keep asset publishing in your deploy pipeline. Because the panel depends on distributed compiled assets, treat publishing as a deploy step rather than a one-off:

php artisan vendor:publish --tag=package-assets --force
php artisan optimize:clear

--force is required on upgrades; without it, Laravel silently skips existing files and you keep the old bundle.

Gate the panel behind your own middleware. Rather than relying on package defaults, register the panel's middleware stack in config to match your app's auth/authorization:

// config/package.php
'middleware' => ['web', 'auth', 'can:access-panel'],
'path' => 'admin',

Customize by overriding views, not editing vendor files. Publish views to resources/views/vendor/package/ and extend the package's layouts. Any direct edits under vendor/ are wiped on composer update — a real risk given this release changed the asset bundle.

Treat the panel as a presentation layer. Resolve data through your own services/repositories and pass it in; avoid letting panel config accumulate business logic. This keeps upgrades (like 1.0.1) low-risk.

Cache-bust in production. If you serve assets via asset() with a version query string or Vite manifest, make sure the panel's published assets participate — otherwise users hold stale CSS after upgrading to 1.0.1.

Gotchas and Tips

• The 1.0.1 fix is the big one. Styles and scripts weren't compiled, so the panel loaded without its front-end. After upgrading: re-publish assets with --force, run php artisan optimize:clear, and hard-refresh the browser. Confirm files exist under public/vendor/<package>/.
• vendor:publish without --force is a silent no-op. This is the most common reason an upgrade "doesn't fix" the styling.
• Browser and CDN caching mask the fix. Bust caches or add a version query; otherwise 1.0.1 looks identical to 1.0.0.
• Wrong asset base URL. If the panel 404s on CSS/JS, check APP_URL and whether asset() resolves to the correct host behind a proxy (TrustProxies).
• Compiled assets mean no build step for consumers — but no source maps either. Debugging panel JS means reading minified bundles; open issues upstream rather than patching public/vendor/.
• Config caching traps. After changing panel path or middleware, run php artisan config:clear; stale cached config is a frequent source of "my change did nothing."
• Extension points: config file for panel behavior, published views for markup, middleware for access control, and package events/service bindings where exposed. Prefer these over subclassing internals, which are not covered by semver guarantees.
• Pin ^1.0.1 in composer.json and note the minimum in your project README so teammates don't reproduce the unstyled-panel issue on fresh clones.