Easel Laravel Package

Getting Started

Easel is a Laravel package from the CNVS org (the team behind the Canvas publishing platform) and is best understood as a scaffolding/UI layer for Canvas-style applications rather than a standalone framework. Treat the package as “glue you compose with,” not something you build on top of in isolation.

Minimal steps:

1. composer require cnvs/easel and confirm your Laravel major is compatible — check the require block in the package’s composer.json before trusting the README, since CNVS packages track Laravel releases closely.
2. Laravel auto-discovery usually registers Cnvs\Easel\EaselServiceProvider. Verify with php artisan about or by grepping vendor/cnvs/easel/composer.json for the extra.laravel.providers key.
3. Publish what the package exposes: php artisan vendor:publish --provider="Cnvs\Easel\EaselServiceProvider" (list available tags first with --list — CNVS packages typically split config, views, and assets tags).
4. Skim these files in order before writing any code: README.md, src/EaselServiceProvider.php (bindings + publish paths), config/easel.php (the knobs you can turn), then src/ alphabetically to see the surface area.

First use case: boot an existing Laravel app, publish the config and views, register the package’s route/middleware group (if it ships one) behind auth, and render the default Easel view in a throwaway route. That one loop tells you whether the package is “config-only,” “view-only,” or expects to own a chunk of your admin surface.

Implementation Patterns

Service-provider-first integration. CNVS packages lean on Laravel’s container. Bind the package’s contracts in AppServiceProvider::register() if you need to swap implementations, and reach for config('easel.*') in your own service providers rather than hard-coding values the package already exposes.

View namespace overrides. Most Easel-style packages register a easel:: view namespace. To customize without forking, publish the views and override via View::prependNamespace('easel', resource_path('views/vendor/easel')) in a service provider’s boot(), or override at the Blade component level if the package ships class-based components.

Compose, don’t extend. If the package exposes Blade components (cards, canvases, panels), your application views should wrap them rather than subclass them. Wrapping gives you a stable seam when the package bumps versions.

Pair with cnvs/canvas deliberately. Easel is most useful when a Canvas install already owns content models (posts, users, tags). Read Canvas’s models into your own view-models/controllers and let Easel render the presentation layer; don’t reach across package boundaries into Canvas internals from Blade.

Middleware and route grouping. If Easel ships routes, keep them in their own route file and wrap with your own auth/verified middleware rather than editing the vendor routes. Mirror the pattern you’d use for Horizon or Telescope: isolate, don’t mutate.

Testing. Use RefreshDatabase and the package’s own test helpers if present (grep -r "function assert" vendor/cnvs/easel/src). For UI behavior, assert on rendered view names (e.g., $response->assertViewIs('easel::...')) rather than raw HTML, so package view changes don’t break your suite.

Gotchas and Tips

• Low adoption signal. With zero dependents and an empty star count on this listing, you are effectively the QA team. Pin the exact version in composer.json ("cnvs/easel": "x.y.*") and read the changelog before any composer update.
• Config caching surprises. Any env() call inside the package config file stops resolving after php artisan config:cache. If behavior changes between serve and a cached deploy, this is why — move environment reads into your own config.
• Publish tags are not obvious. Always run vendor:publish --list first; guessing the tag silently no-ops and you’ll spend an hour wondering why your view override isn’t taking.
• Namespace collisions with Canvas. Both packages live under Cnvs\. An accidental use Cnvs\Easel\... in a file that wanted a Canvas class is a real risk; rely on the IDE’s fully-qualified hint rather than autocompletion.
• Asset pipeline coupling. If Easel ships compiled CSS/JS (or Tailwind config), a Vite migration in your app can orphan them. Check resources/ in the package before you assume it just emits markup.
• Debugging route/view registration. php artisan route:list --path=easel and php artisan view:cache are your first two commands when “it renders blank.” A missing view namespace produces a silent empty render more often than an exception.
• Extension points, in order of safety: config → published views → container bindings → view namespace overrides → macros → forking. Never fork until you’ve tried bindings plus namespace overrides; CNVS’s packages tend to be small enough that a fork is cheap, but diverging silently is worse.
• Version support window. If the package targets an older Laravel than your app, test on a branch first. These niche packages are frequently abandoned mid-major-release, and a Laravel bump can quietly break service-provider registration with no error until runtime.