Extension Structure
Capell extensions are Laravel packages that add one focused capability through public Capell extension points. Keep extension code outside the core packages unless the feature belongs to the platform foundation.
Use this page as the routing guide before creating a package, adding a provider, or changing package docs.
Choose the extension shape
Section titled “Choose the extension shape”| Need | Use | Start with |
|---|---|---|
| Add a first-party optional feature | Add-on package in capell-app/packages |
Package Authoring |
| Add fields, actions, tools, pages, resources, or dashboard widgets to the admin | Admin extension points and tagged extenders | Admin Extensions |
| Add frontend output, render hooks, theme assets, Blade components, Livewire components, or route behavior | Frontend extension points | Frontend Extensions |
| Add a package that ships migrations, settings, actions, routes, translations, and tests | Standard package anatomy | Package Anatomy |
| Register a core CMS type, schema, event subscriber, render hook, or model binding | Core extension point | Extending Capell |
Prefer the narrowest extension point that owns the behavior. A tagged extender is usually safer than replacing a resource. A render hook is usually safer than overriding a theme view. Publishing core schemas should be the last option because published files stop receiving upstream changes.
Package boundaries
Section titled “Package boundaries”An extension package should have one clear runtime shape:
sharedproviders for package registration, config, translations, and container bindings used in more than one runtime.adminproviders for Filament pages, resources, widgets, settings contributors, admin extenders, and Extensions page actions.frontendproviders for render hooks, Blade components, Livewire components, routes, themes, and frontend assets.consoleproviders for install commands, import/export commands, scheduled work, and developer tooling.
Declare the same boundary in capell.json through contexts, requires, and providers. Do not boot admin-only classes on frontend requests.
Documentation for extensions
Section titled “Documentation for extensions”Every documented package should have:
README.mdas the package landing page.capell.jsonwithname,kind,capell-version,productGroup,tier,bundle,contexts,requires, and provider metadata.docs/**for deeper install, admin, frontend, database, testing, or integration guides.- Public screenshots or diagrams only when they help someone configure, extend, or verify the package.
The Capell Extensions explorer is generated from those files. If an extension is missing or grouped incorrectly, fix capell.json before changing this docs site.
Review checklist
Section titled “Review checklist”- Business logic lives in Actions or services, not Filament resources or page classes.
- User-facing strings are translated by the package.
- Runtime providers match the manifest contexts.
- Destructive or data-changing behavior has direct Action tests.
- Admin/editor behavior is not leaked into public frontend output.
- Public docs explain install, configuration, extension points, and failure modes the package actually has.