Plinth Laravel Package

Technical Evaluation

Assessment confidence: low. This is the first assessment on record and the only evidence available is the v0.1.1 release note plus a pointer to v0.1.0. Everything below should be treated as a hypothesis to validate, not a conclusion.

Architecture fit

• Plinth is distributed as a paired Composer package (ptbdynamic/plinth) and npm package (@ptbdynamic/plinth), with frontend subpaths for vue, react, tokens, and css. That shape indicates a design-system / UI-kit artifact with a thin Laravel-side delivery layer rather than a backend library.
• Fit is therefore strongest where we have a Laravel application with a Vue or React front end and a shared token/theming need. It is a poor fit for Blade-only or API-only services — there is no evidence of Blade components, service providers, migrations, or config publishing in the release note.
• The dual-registry symmetry (GitHub org = Composer vendor = npm scope) is a genuine architectural positive: one namespace to reason about, one version number to pin across PHP and JS.

Integration feasibility

• Installation is a two-command, standard-registry install. No private registry or auth path is implied.
• Real integration cost is unknown because v0.1.1 tells us where the package lives, not how it wires up. Whether Laravel needs a service provider, whether tokens are published via vendor:publish, and whether the CSS subpath is intended to be imported into a Vite build are all unresolved.
• The frontend subpath split (vue vs react) is a positive signal for tree-shaking and for not forcing a single framework choice, but it also means we must confirm which one we standardise on before committing.

Technical risk

• Pre-1.0 maturity (high). v0.1.x with a release that is purely a packaging fix implies the public API is not yet stabilised. No deprecation policy exists to rely on.
• Renaming churn (medium, contained). v0.1.1 moved the npm package to @ptbdynamic/plinth. Subpaths are explicitly unchanged, which limits blast radius, but this is a rename at the distribution layer — the class of change most likely to recur before 1.0.
• Evidence gap (high). No prior assessment, no usage data, no documented adopter base. We are assessing a package we have never run.
• Abandonment risk (unknown). Single-organisation package; no signal on maintainer count or release cadence.

Key questions

1. Does the Composer package register a service provider, and is any vendor:publish step required for config or assets?
2. Are tokens and css consumed via npm imports, or does the PHP side emit them? This determines whether our asset pipeline or our PHP layer owns theming.
3. Do the Vue and React subpaths share a single token source, and is that source versioned in lockstep with the PHP package?
4. What is the intended support matrix — Laravel version range, PHP version range, Vite vs Mix, Vue 2/3, React 17/18?
5. Is there a documented upgrade policy or a stated target date for 1.0?
6. Is there any licensing, security disclosure, or maintainer-response commitment?

Integration Approach

Stack fit

• Best fit: existing Laravel app on a modern build tool (Vite) with a Vue or React front end that currently has ad-hoc or duplicated design tokens.
• Weak fit: Blade-rendered apps, legacy Mix/Webpack pipelines, or teams without a frontend framework where the /vue and /react entry points are dead weight.
• Neutral: greenfield projects — attractive for consistency, but starting on a 0.1.x design system front-loads upgrade work into the period when the product is changing fastest.

Migration path

• Assume there is nothing to migrate from — we have no incumbent Plinth usage. This is a net-new adoption decision, not an upgrade.
• For the small population that may have pulled v0.1.0 from npm under a previous name: the v0.1.1 rename requires a dependency-line change only. Subpaths are unchanged, so imports survive. Treat as a low-effort, mechanical fix.
• For consumers not yet on the package, there is no migration burden at all — adopt directly at v0.1.1.

Compatibility

• Unverified. The release note asserts subpath stability, which is a compatibility promise about one axis only (import paths). It says nothing about Laravel version support, PHP version floor, or peer-dependency ranges for Vue/React.
• The dual-registry mirror is only safe if the PHP and JS versions are released together. Nothing in the note commits to that; confirm before pinning.
• Pin exact versions in composer.json and package.json — do not use caret ranges on a 0.1.x package.

Sequencing

1. Spike (1–2 days): install both packages in a disposable branch, verify service provider / publish behaviour, and confirm the Vue or React subpath actually builds under our Vite config.
2. Compatibility gate: pin down the Laravel/PHP/framework support matrix against our actual versions before writing any product code.
3. Pilot: adopt on one low-risk surface (a settings page or an internal admin screen) to exercise tokens and theming end to end.
4. Decide: either standardise and document, or retire the spike. Do not adopt partially across multiple surfaces before the pilot concludes.
5. Defer the second framework subpath until the first is proven — running Vue and React off one design system doubles the surface we must re-verify at each 0.x release.

Operational Impact

Maintenance

• Expect upgrade work on an unpredictable cadence. Pre-1.0 packages with packaging-layer churn (as v0.1.1 demonstrates) tend to produce frequent small breaking changes rather than rare large ones.
• Budget a recurring line item: someone must re-verify the pinned version against our build on a monthly basis at minimum. This is cheap now and grows with every surface that adopts it.
• If we adopt, we own vendoring risk: no internal fork, no patch capacity assumed.

Support

• No stated support commitment, SLA, or security-disclosure process. Escalation path is a public GitHub issue against a single organisation.
• Internal support burden falls on whichever team adopts first; there is no vendor to escalate to. Name that team before adoption, not after.
• Documentation is the release notes. Assume self-serve only.

Scaling

• Technically the package scales fine — a design system is static assets and tokens, not a runtime dependency with state. No throughput, memory, or concurrency concerns at our likely volume.
• The scaling constraint is organisational: the more surfaces adopt it, the more expensive a breaking 0.x release becomes to absorb. Cost per upgrade scales linearly with adoption; adoption should therefore scale deliberately, not opportunistically.
• Version-skew risk grows with adoption: if the Composer and npm packages drift apart, we get mismatched tokens across PHP and JS. Pin both, upgrade both together.

Failure modes

• Silent version skew: PHP package and npm package pinned to different versions → tokens and rendered components disagree. Mitigation: upgrade in lockstep, assert versions in CI.
• Registry rename recurrence: another v0.1.1-style rename breaks a fresh npm install from a clean cache while existing lockfiles keep working — failures surface on new environments and CI rebuilds, not locally. Mitigation: committed lockfiles, clean-install check in CI.
• Build-pipeline breakage: the css/tokens subpaths may depend on a specific bundler assumption. Failure appears as styling regressions, not errors — the hardest kind to catch. Mitigation: visual smoke check in the pilot.
• Upstream abandonment: no successor, no fork plan. Mitigation: because it is a design system, the exit is unusually clean — tokens and CSS are portable. Keep our own token definitions as the source of truth rather than inverting the dependency.

Ramp-up

• Low for a frontend-comfortable team: two installs, one import, standard Vite handling. Hours, not days.
• Non-trivial for the decision, not the install: the unanswered questions in Technical Evaluation (service provider, token ownership, support matrix) each gate whether the install is the right move. The spike is cheap; skipping it is not.
• Recommend a named owner and an explicit expiry on the pilot. A 0.1.x dependency adopted without a revisit date tends to become permanent by default.