Filament Tutorials Laravel Package

Getting Started

coringawc/filament-tutorials is a Filament panel plugin for building in-panel onboarding: ordered tutorial steps that point at UI elements and walk admins through a workflow. It is aimed at replacing ad-hoc "welcome" modals with content you can manage from the admin panel.

Minimal setup:

composer require coringawc/filament-tutorials
php artisan vendor:publish --tag="filament-tutorials-migrations"
php artisan migrate

Register the plugin on the panel you want tutorials in:

use CoringaWc\FilamentTutorials\FilamentTutorialsPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(FilamentTutorialsPlugin::make());
}

Then publish config if you need to change defaults:

php artisan vendor:publish --tag="filament-tutorials-config"

Where to look first:

1. The README for the exact plugin class name and publish tags (these change between 0.1.x releases).
2. config/filament-tutorials.php for table names, navigation settings, and default behaviour.
3. The plugin service provider in vendor/coringawc/filament-tutorials/src/ to confirm which resources, pages, and Livewire components are registered.
4. The migrations, to understand the tutorial/step schema before you seed content.

First useful use case: create a single "Getting started" tutorial with a handful of steps targeting the dashboard navigation, the create button on your main resource, and the user menu. Assign it to new admin users only. This gives you a real end-to-end test of the schema, the targeting mechanism, and completion tracking before you invest in authoring dozens of tutorials.

Version note: v0.1.18 is a patch release with no published change description beyond the GitHub compare link. Treat the upgrade as low-risk if you are already on 0.1.x, but since the package is pre-1.0, read the diff before bumping if you extend its models, override views, or depend on internal class names.

Implementation Patterns

Seed tutorials rather than hand-authoring them. Onboarding content is application configuration, not user data. Put tutorials and steps in a seeder so every environment (and every new developer) gets the same baseline. Reserve the admin UI for tweaking copy after launch, and export those tweaks back into the seeder when they stabilise.

Use stable selectors for step targets. Tutorial steps usually target DOM elements. Filament's generated markup includes utility classes and hashed identifiers that change between releases. Attach your own attribute to anchor elements instead:

TextInput::make('name')
    ->extraAttributes(['data-tour' => 'customer-name']);

Then target [data-tour="customer-name"] in the step. This survives Filament upgrades and makes the tutorial definition readable.

Scope tutorials per panel and per tenant. If you run multiple panels, register the plugin only where tutorials belong, or gate content by panel. With Filament tenancy enabled, make sure tutorial records are tenant-scoped, or a tenant admin will see another tenant's onboarding copy.

Gate by user, not by global state. Show onboarding only to users who have not completed it. Store completion against the user (a tutorials_completed JSON column, a pivot table, or Filament's user preferences) and check it before rendering. Avoid a single global "onboarding done" flag, because it breaks as soon as you add a second admin.

Separate content from presentation. Keep step titles and bodies as translation keys (tutorials.onboarding.step_1.title) rather than hardcoded strings. You get localisation for free and a single place to review copy changes. If your audience is multilingual, author one tutorial per locale and select by app()->getLocale().

Author in config for review, in the database for speed. Config-defined tutorials go through code review and deploy with the release; database-defined tutorials can be edited live but are invisible in diffs. A workable split: define the tutorial skeleton and step order in config/seeders, and allow only copy edits in the admin UI.

Test the happy path in Livewire tests. Assert that a new user sees the tutorial and a completed user does not. This catches the two most common regressions: authorization leaking tutorials to users who should not see them, and completion state not being read.

Wire completion into your existing onboarding checklist. If you already have a "setup checklist" widget, mark tutorial completion as one of its items rather than maintaining two separate progress systems.

Gotchas and Tips

• Pre-1.0 churn. At 0.1.x, minor releases can rename classes, change publish tags, or adjust the schema. Pin the version in composer.json ("coringawc/filament-tutorials": "0.1.18") and upgrade deliberately. Patch releases like 0.1.18 carry no documented breaking changes, but the changelog is only a compare link — check the diff if you override anything.
• Asset and cache clearing. After upgrading, run php artisan filament:assets and php artisan optimize:clear. A stale cached config is the most common reason a config change appears to do nothing; run php artisan config:cache in production after editing the published config.
• Selector fragility. If steps silently stop highlighting, the target element moved or was renamed. Filament upgrades are the usual culprit. Keep the data-tour convention and add a smoke test that asserts each configured selector exists on the relevant page.
• Authorization defaults. Tutorials are typically visible to every user with panel access. If some tutorials describe privileged workflows, add a policy or a visibility check rather than relying on users not clicking them.
• Query count. Loading tutorials with their steps can produce N+1 queries on every panel page. Eager load steps (with('steps')) and consider caching the active tutorial for the request.
• Publish tags drift. If vendor:publish reports nothing to publish, the tag name has changed. List available tags with php artisan vendor:publish --provider="CoringaWc\FilamentTutorials\FilamentTutorialsServiceProvider" and check the README for the current names.
• Plugin registration order. Registering the plugin after other plugins that alter navigation or the user menu can change where tutorial entry points appear. If the tutorials page is missing from navigation, check plugin order and navigation group configuration.
• Extension points worth knowing: override the step renderer view (publish views, then point the config at your view), add custom step types if the package exposes a step contract, and use a policy on the tutorial model to control who can manage content. These are the safest places to customise; subclassing internal Livewire components is the most likely to break on a patch release.
• Debugging: use php artisan about to confirm the plugin is discovered, Laravel Telescope or DB::listen to inspect tutorial queries, and the browser inspector to verify your data-tour attributes are actually rendered (Filament may strip unknown attributes on some components).
• Migration caution. If you published migrations early, a later release that alters the same tables will not update your published copy. Compare published migrations against the package's database/migrations directory after each minor upgrade.