Craft View

Skill: Craft View

"Published views assert stability across the major version. Every vendor:publish is a promise." -- Dan Harrin

The Standard

1. Namespace Everything: Register views with loadViewsFrom() using a namespace. Always package::view-name. Never pollute the global view namespace. Collisions with other packages or the app itself are silent and maddening.

   $this->loadViewsFrom(__DIR__.'/../resources/views', 'courier');
   
   // Consumer usage
   return view('courier::dashboard');
   

2. Published Views Are a Contract: When consumers publish your views, they expect those views to remain stable within the major version. Changing published view structure in a minor release breaks every consumer who customized them. Treat published views like a public API.

3. Blade Component Registration: Three approaches, matched to the need.

   Approach	Method	When
   Explicit alias	Blade::component('pkg-alert', AlertComponent::class)	One-off components, maximum clarity
   Component namespace	Blade::componentNamespace('Vendor\\Views\\Components', 'pkg')	Many components, auto-discovery via <x-pkg::alert />
   Anonymous components	Place in resources/views/components/	Simple markup-only components, no class needed

   Spatie's PackageServiceProvider handles this: ->hasViewComponents('spatie', Alert::class, Card::class) registers components with the <x-spatie-alert /> prefix.

4. Anonymous Components in Packages: Place them in the components/ subdirectory of your views directory. They are auto-discovered once loadViewsFrom() is registered. Consumer usage: <x-courier::alert />.

5. CSS Framework Agnosticism: Never hardcode Tailwind, Bootstrap, or any CSS framework in package views. Either ship unstyled views with CSS classes consumers can target, or use a configurable theme approach. Filament's pattern: a design system of Blade components that abstracts the CSS framework entirely.

6. View Publishing Groups: Namespace publish tags as {package}-views. Let consumers publish only what they need. Never bundle views with config in a single publish tag.

   $this->publishes([
       __DIR__.'/../resources/views' => resource_path('views/vendor/courier'),
   ], 'courier-views');
   

7. View Composers for Shared Data: When views need data that doesn't come from the controller, use view composers. Register them in the service provider. Keep the composer class focused -- single concern, no side effects.

   View::composer('courier::*', function ($view) {
       $view->with('courierVersion', Courier::VERSION);
   });
   

8. Livewire Component Registration: For packages that ship Livewire components, register them explicitly with Livewire::component(). Use a consistent naming convention: package-name::component-name.

   use Livewire\Livewire;
   
   Livewire::component('courier::tracking-widget', TrackingWidget::class);
   

9. Render Hooks: For packages that need to inject UI into specific locations (admin panels, dashboards), provide named render hooks. Filament's pattern: renderHook('panels::body.start'). Consumers register content at hooks without modifying views.

10. View Override Priority: Laravel checks resources/views/vendor/{package}/ before the package's own views directory. This is automatic once you use loadViewsFrom(). Document which views are safe to override and which are internal.

The Anti-Patterns

Real-World Examples

See examples.md.