Addon Modules

Addons are the freest type. Core has no conventions it looks for inside one, so you’re writing a normal Laravel and Inertia feature that happens to live in Modules/Addons/.

Read Fundamentals first if you haven’t.

Generate it

php artisan make:module LoyaltyRewards --type=addon
php artisan module:enable LoyaltyRewards
php artisan module:migrate LoyaltyRewards
php artisan module:doctor LoyaltyRewards

What you get

Modules/Addons/LoyaltyRewards/
├── module.json                 with permissions declared
├── app/
│   ├── Providers/
│   ├── Http/Controllers/SettingsController
│   └── Models/LoyaltyRewardsCredential   rename or delete this
├── database/migrations/
└── routes/                     web, api, settings

The generated credentials model assumes you talk to an external API. If you don’t, delete it and its migration, and swap the settings controller over to a key-value settings table instead.

How addons differ

	Service modules	Gateways	Addons
Classes core looks for	~12	1	none
Registration	By name	Explicit	you drive it

Everything happens through four things: routes you register, listeners on core events, Inertia pages in register.ts, and your own tables.

Hooking into core

Events are the main integration point. Register them in EventServiceProvider:

protected $listen = [
    \App\Events\ServicePaymentCompleted::class => [AwardPurchasePoints::class],
    \App\Events\ServiceRenewalInitiated::class => [AwardRenewalPoints::class],
    \Illuminate\Auth\Events\Registered::class => [GiveSignupBonus::class],
];

The full list is in Fundamentals.

Two things to get right there: keep configureEmailVerification() as a no-op, and never list a listener that already lives in app/Listeners.

Queue your listeners:

class AwardPurchasePoints implements ShouldQueue
{
    public function handle(ServicePaymentCompleted $event): void { /* ... */ }
}

An addon that throws inside a synchronous listener can break checkout for everyone.

Affiliates is the best reference here. It listens to registration, payment and renewal, and does payouts off the back of them.

Settings

Flat fields
Custom UI
Key-value store

Keep the generated SettingsController and just change the fields. You get a full admin page with no React. See the settings section.

Like Forms does with its 12 pages. Write your own controller and page, then register it:

resources/js/register.ts

registerModulePages({
    'LoyaltyRewards/Settings': () => import('./Pages/Admin/Settings.tsx'),
    'LoyaltyRewards/Dashboard': () => import('./Pages/User/Dashboard.tsx'),
});

A small table and model is the usual pattern:

class LoyaltySetting extends Model
{
    protected $table = 'loyalty_settings';
    protected $fillable = ['key', 'value'];

    public static function get(string $key, mixed $default = null): mixed
    {
        return static::where('key', $key)->value('value') ?? $default;
    }
}

Seed sensible defaults so the module works the moment it’s enabled. Affiliates does this with AffiliateSettingsSeeder.

User-facing routes

routes/web.php

Route::middleware(['auth', 'verified', CheckUserSuspension::class])->group(function () {
    Route::get('/rewards', [RewardsController::class, 'index'])->name('rewards.index');
    Route::post('/rewards/redeem', [RewardsController::class, 'redeem'])->name('rewards.redeem');
});

Admin routes and their permissions are already set up by the generator. See Admin permissions if you need to add more.

There’s no manifest hook for sidebar links. They come from the SidebarLink table, which admins manage in the admin panel.

So either seed a row when your module is enabled, which is friendlier, or document the URL and let the admin add it:

SidebarLink::firstOrCreate(
    ['url' => '/rewards'],
    ['label' => 'Rewards', 'icon' => 'gift', 'is_active' => true, 'order' => 50],
);

Commands and cron

protected function moduleCommands(): array
{
    return [ExpireLoyaltyPoints::class];
}

protected function moduleSchedule(Schedule $schedule): void
{
    $schedule->command('loyalty:expire-points')->daily();
}

Use moduleSchedule() or routes/console.php, not both.

Touching core data

Adding a column to users or services is fine. Make it nullable and the migration idempotent:

if (! Schema::hasColumn('users', 'loyalty_points')) {
    Schema::table('users', fn (Blueprint $t) => $t->unsignedInteger('loyalty_points')->default(0));
}

Never change or drop a core column, and don’t edit App\Models\User. Point a relationship at it from your own model instead:

class LoyaltyAccount extends Model
{
    public function user(): BelongsTo
    {
        return $this->belongsTo(\App\Models\User::class);
    }
}

If you need more than one field, prefer a side table with a foreign key. It keeps your module removable.

Test it

php artisan module:doctor LoyaltyRewards

Enable it

Migrations run, defaults seed, admin page loads.

Trigger each event you listen to

Check the side effects.

Disable it, and confirm the app still works completely

Nothing in core should depend on your tables, listeners or routes.

Re-enable it

No duplicate rows, no failed migrations.

Step 3 is the one people skip and the one that breaks production.

Worth reading

LoyaltyProgram

Small and event-driven.

News

Content CRUD with admin and public pages.

Affiliates

Listeners, payouts, a console command, 4 React pages.

Forms

The most frontend-heavy, 12 pages.

Affiliates, Blog, KnowledgeBase and News still use an older hand-written service provider. Copy their features, not their providers.

GETTING STARTED

MAKE YOUR OWN

SPARTAN THEMES

Generate it

How addons differ

Hooking into core

Settings

User-facing routes

Navigation

Commands and cron

Touching core data

Test it

Worth reading

LoyaltyProgram

News

Affiliates

Forms

​Generate it

​How addons differ

​Hooking into core

​Settings

​User-facing routes

​Navigation

​Commands and cron

​Touching core data

​Test it

​Worth reading

LoyaltyProgram

News

Affiliates

Forms

Generate it

How addons differ

Hooking into core

Settings

User-facing routes

Navigation

Commands and cron

Touching core data

Test it

Worth reading