Product Decisions This Supports
- Build vs. buy for admin-side RBAC: this package supplies the roles-and-permissions management surface inside the MoonShine admin panel, so the team avoids building a custom CRUD UI for roles, permissions, and their assignment. That is typically days-to-weeks of design, UI, and edge-case work (guarding against privilege escalation, self-lockout, and orphaned roles) that is not differentiating for most products.
- Roadmap sequencing around MoonShine v4: 4.0.0 is explicitly an alignment release ("Добавлена поддержка moonshine v4"). It is the gate that lets the platform upgrade to MoonShine v4 without losing admin RBAC. If the MoonShine v4 upgrade is on the roadmap, this release unblocks it; if it is not, adopting 4.0.0 forces that upgrade early.
- Dependency and version-pinning policy: the package moves in lockstep with MoonShine majors (3.1.0 → 4.0.0). This is a "pin to the matching major and upgrade in pairs" dependency, not an independently versioned library. Treat MoonShine and this package as a single upgrade unit in planning and estimation.
- Feature scope decision: whether RBAC administration lives in the admin panel or in code/config. This package bets on "in the panel" — appropriate when non-engineers (ops, support leads, customer admins) are expected to manage roles, and overkill when permissions are effectively static and defined by developers.
- Multi-tenant / per-customer admin use cases: relevant where each customer or business unit needs its own role definitions and the product needs a self-service access model without a bespoke back office.
When to Consider This Package
Adopt when most of the following hold:
- The product runs on MoonShine v4 (or the team is committed to upgrading now). Version 4.0.0 is scoped to MoonShine v4; teams still on MoonShine v3 must stay on 3.1.0 and will not receive this line of updates.
- Authorization logic is already (or will be) role/permission-based rather than policy- and attribute-heavy. If access rules are mostly
Gate::define/policy logic with contextual conditions, a roles/permissions CRUD UI adds surface area without adding much value.
- Non-engineers need to manage access — or the team wants to stop shipping code changes for routine permission tweaks.
- The team is comfortable with a small, single-maintainer ecosystem dependency for a security-adjacent capability, and is prepared to review the generated schema and guardrails rather than trusting defaults.
Look elsewhere (or build in-house) when:
- You are not on MoonShine, or you are on MoonShine v3 with no near-term upgrade — the major-version coupling means you inherit an upgrade project.
- You need enterprise-grade access governance: approval workflows for role changes, immutable audit trails, segregation-of-duties rules, SSO/SCIM-driven group sync, or time-bound/just-in-time elevation. Those requirements will exceed a panel CRUD package and are better served by a dedicated authorization service.
- You need fine-grained ABAC/contextual rules (per-record, per-tenant, per-condition) — model that directly in policies rather than bending a role table.
- Supply-chain risk tolerance is low. A security-relevant admin dependency maintained by a single author, with release notes in a single language and no published security policy, warrants a documented risk acceptance and a plan to fork or replace. Verify maintenance cadence and issue responsiveness before committing.
- Compliance obligations require vendor due diligence the project cannot satisfy (no SLA, no CVE process, no published support window).
How to Pitch It (Stakeholders)
One line: A drop-in roles-and-permissions management screen for our MoonShine admin panel — version 4.0.0 is the release that makes it compatible with MoonShine v4.
For executives: This replaces a build we would otherwise own: an admin UI for creating roles, assigning permissions, and managing who can do what. It is a small, focused dependency rather than a platform commitment, and it removes a recurring source of "can you just change this permission for me" engineering tickets by putting access control in the hands of operations. The cost is a dependency we do not control, in a security-sensitive area, maintained by a very small team — so we treat it as "buy with a contingency," and the contingency is a fork of a few screens, not a rewrite of our authorization model.
For engineering: 4.0.0 is a compatibility release for MoonShine v4, not a feature release — the only substantive change is the version alignment. Consequences: (1) the package and MoonShine are effectively a single upgrade unit, so plan and test them together; (2) upgrading to MoonShine v4 without also upgrading this to 4.0.0 will break admin RBAC, and staying on MoonShine v3 caps us at 3.1.0; (3) upgrading to 4.0.0 is a breaking change for anyone on the 3.x line and should be treated as a major upgrade with a regression pass over role/permission screens and seeded data. Before adoption, review the underlying permission tables and how permission checks are wired, confirm the guard model matches ours, and satisfy ourselves that role changes cannot be used to escalate privileges or lock out the last administrator.