Tutorials Laravel Package

Product Decisions This Supports

• Build vs. buy for onboarding and in-app education. guava/tutorials ships the commodity scaffolding — tutorial definitions, ordered steps, action handling, publish controls, per-user progress records, Blade rendering. That reframes the decision from "do we staff an onboarding squad?" to "do we buy four weeks of scaffolding and spend our engineers on targeting, analytics, and copy?" For most teams the answer is yes, provided the exit cost stays low (self-hosted, Laravel-native, no SaaS contract, thin wrapper around it).
• Whether activation is a product surface or a side quest. Step-based flows are the delivery mechanism for "first project created," "first integration connected," "first invite sent." Committing to a package like this is a public statement that onboarding gets named content owners, sequencing decisions, and completion metrics — not an ad hoc UI ticket that gets deprioritized every sprint. This is often the most consequential decision the package informs, and it is organizational, not technical.
• Personalization scope: segment-aware guidance vs. per-segment content duplication. The 1.1.0 Closure support on action properties is the commercially interesting feature. One approved tutorial artifact can emit a different CTA, URL, or destination per plan, role, or tenant at runtime. That turns "Enterprise users need a different second step than trial users" from a content-management problem (two tutorials, two maintenance streams, two sets of translations, guaranteed drift) into a configuration problem. It is also the strongest reason to prefer this over a static tour library.
• Market expansion sequencing — specifically RTL locales. Persian translations plus an RTL alignment bug fix in a minor release tells you the presentation layer is being exercised in RTL but is still maturing. If an RTL market is on the roadmap, this is an early signal: someone has walked the path, but you should budget a theming/QA pass rather than assume it's covered. Conversely, if RTL is not on the roadmap, that work is irrelevant to your evaluation and the package's real value narrows to the core CRUD-plus-progress model.
• Vendor concentration and roadmap risk. This is a single-maintainer agency package at v1.1.0 with essentially zero dependent ecosystem, no stated SLA, and no commercial support path. That is a fine profile for a non-differentiating surface — and a bad one for anything on the critical activation path without a fallback. The PM decision is explicitly about blast radius: which surfaces can tolerate a maintainer going quiet for two quarters, and which cannot.
• Measurement strategy, and the cost of retrofitting it. The package renders guidance; it does not measure it. There is no funnel analytics, no A/B variant assignment, no holdout group, no audience-targeting engine. If onboarding effectiveness is a metric you intend to report on — and it should be — the instrumentation is not a follow-up ticket. It ships in the first PR or you relaunch the flow to get a baseline. Budgeting that up front is a PM call, not an engineering one, because it's the difference between a quarter of learning and a quarter of anecdotes.
• Roadmap sequencing for the targeting layer. The package deliberately stops at rendering and progress. "Which tutorial should this user see right now?" — a function of roles, plans, tenancy, entitlements, and completion state — is left to you. That is a scoping decision worth naming out loud: the buy covers the presentation and persistence of guidance, not the decision of what guidance to show. Teams that assume otherwise will discover mid-sprint that the hard half is still theirs.

When to Consider This Package

Adopt when most of these hold:

• You are on a current Laravel version and want onboarding as a first-party surface, not a third-party JS overlay injected into your app — data residency, auth scoping, and tenancy all stay inside your existing stack.
• You have two or more tutorials planned, or one tutorial that will iterate. A single one-off tooltip tour does not justify a package; a recurring onboarding surface across releases does.
• Guidance needs to vary by plan, role, or tenant in ways your own code already understands. The Closure action properties plus your own selection service is the clean answer here.
• You can afford one to two developer-days for the spike and roughly a sprint to productionize content, targeting, theming, and instrumentation — and you have a named engineer to own it afterward.
• Onboarding sits on a supporting surface (secondary activation, feature adoption, admin education) where a quarter of maintainer silence degrades the experience rather than breaking the product.
• You already have an analytics pipeline to emit tutorial_shown / step_viewed / completed / dismissed into. Without one, half the value evaporates and you are shipping blind.

Look elsewhere — or build — when:

• Onboarding is your activation engine. If tutorial completion is a primary driver of conversion on a business-critical path, a single-maintainer v1.1.0 package with no dependents and no support contract is the wrong risk profile. Either build the thin slice yourself (it is genuinely small: a steps table, a progress table, an overlay) or pay for a commercial platform with an SLA.
• You need experimentation inside the flow. No A/B assignment, no variant routing, no holdout. You can layer your own flag system on top, but if experimentation is the core requirement, evaluate tools where it's native rather than bolting it on.
• You need rich targeting and audience segmentation out of the box. The package gives you definitions and progress, not eligibility. If the product requirement is "show the right tutorial to the right user" and you don't have a clean place to put that logic, you're buying a rendering engine and still owning the hard problem.
• The frontend is not Blade-first. Overlay tutorials bind to DOM in your application. A React/Vue SPA with client-side routing means you're consuming the API and rebuilding the presentation layer anyway — at which point the package's value is a schema and some CRUD, and you should price it accordingly.
• You want a drop-in visual experience. The RTL fix shipping as a minor-release bug fix is a maturity signal on the presentation layer. Treat it as a theming pass against your design system, not a component you adopt as-is. If design fidelity is non-negotiable and you have no frontend capacity to invest, this is friction.
• You cannot tolerate selector-drift maintenance. Overlay steps bind to your DOM. Every refactor of a target page is a potential silent breakage with no error. You need a data-tutorial convention and a CI check that asserts targets exist. Teams that can't sustain that discipline will end up with tutorials that highlight nothing and no one noticing.
• Localization is required across many locales on day one. Persian and English are the known coverage; per-locale completeness is undocumented. Missing keys render as raw keys to end users — a very visible failure. Supporting six locales is a translation-gap ownership commitment, not a config toggle.
• Nobody will own it. No internal owner means no upgrade review, no smoke tests, no one to answer "why isn't the tutorial showing?" That's the failure mode that kills these adoptions, and it's organizational.

The honest summary for a PM: this is a credible, cheap, self-hosted primitive with real maturity risk. It is the right buy for teams that already know onboarding is a product surface they intend to own, and the wrong buy for teams hoping a package will supply the product thinking.

How to Pitch It (Stakeholders)

For executives — the one-paragraph version:

We can add guided in-app onboarding in about a sprint instead of a quarter. guava/tutorials is a Laravel package that supplies the parts that are pure plumbing — defining multi-step tutorials, tracking who's completed what, rendering the overlay, controlling what's published — so our engineers spend their time on the things that are actually ours: which user sees which guidance, how we measure it, and how it looks against our brand. It's self-hosted, no vendor contract, no data leaving our stack, and the integration boundary is thin enough that walking away later is a matter of days, not months. The trade-off is real and worth stating plainly: it's a young package from a small shop with one maintainer and no support agreement. That's an acceptable profile for onboarding as a supporting surface — it is not acceptable if onboarding becomes our primary activation lever, so I'd rather validate it on a contained pilot, measure it honestly, and then decide whether to scale it or replace it with something we own. What I need from this decision is a named owner and a small instrumentation budget; without those, we'd be shipping guidance we can't evaluate.

For engineering — the summary they'll actually act on:

• The package is a primitive, not a platform. It gives you tutorial definitions, ordered steps, actions, publish state, progress records, and Blade rendering. It does not give you audience targeting, analytics, A/B testing, or "skip this step if the target element is missing." Put a thin TutorialRegistry boundary between your app and the vendor models from day one — controllers, Blade, and the completion endpoint talk to your service, never to package classes. That boundary is what makes the fork-or-drop decision cheap and keeps targeting logic (roles, plans, tenancy) in the codebase that already understands it.
• The spike has four kill criteria, and they're cheap. Install it, define a three-step tutorial, render it on one authenticated page, complete it. In that process answer: does it pull Filament or Livewire in as a hard transitive dependency we don't want on the customer surface; does it ship pre-built assets or demand a Vite build (this decides config task vs. CSS fork); does config:cache still boot with a tutorial defined; and is the resulting schema one we're willing to own. If any of those is a no, stop before writing content. One to two developer-days, not a sprint.
• Closures are the headline risk, and they're also the best feature. 1.1.0 added Closure support to action properties — genuinely useful for per-plan/per-role variation of one approved tutorial. But closures don't serialize: if a closure-bearing definition lands in a cached config array or a database column, config:cache fails or silently drops it, and Octane workers can hold stale bindings across deploys. Keep closure-bearing definitions in PHP files loaded outside the config cache, keep them pure and cheap, and make config:cache plus an Octane smoke test part of the spike — not launch day.
• Selector drift is our risk, not theirs. Overlays bind to our DOM. Adopt a data-tutorial="..." attribute convention, bind actions to those, and add a CI check that asserts every configured selector exists on its intended page. Otherwise the failure mode is silence: no error, just an overlay highlighting nothing. Same for selection debugging — log which tutorial the registry picked and which were filtered and why, behind a flag, or every "why isn't it showing?" ticket costs 40 minutes.
• Instrumentation and idempotency are in the first PR. Emit tutorial_shown, step_viewed, completed, dismissed through the existing pipeline, and make completion recording a firstOrCreate on (tutorial, step, user) — users double-click and reload. Publish config, migrations, and lang on day one; publish views and assets only when there's a concrete theming requirement, because published views go stale and every upgrade becomes a manual diff. Pin ^1.1, review each release deliberately, and prefer soft-retiring tutorials over deleting them so completion history stays legible.

For design — the scoping note: the visual layer is a theming pass against our design system, not a finished component. Budget for it, and treat RTL support as present-but-maturing rather than solved.