Forms Laravel Package

Getting Started

Coming from a clean install, the shortest path to a working form is:

1. Install the package and its support dependency. The v1.1.0 release imports the localization composable from the laravilt/support package, so make sure that is pulled in (it should arrive as a transitive dependency, but if you have composer.lock pinned from a v1.0.x install, run composer update laravilt/forms laravilt/support).
2. Pick your frontend stack up front. v1.1.0 introduces a React stack alongside Vue. The two are shipped in parallel and are not interchangeable at runtime — decide which one your Inertia app uses before you scaffold anything, because component names, props, and slot conventions differ between them.
3. Publish and inspect the config/assets. Run the vendor publish command (check php artisan vendor:publish --provider="Laravilt\Forms\..." — the provider namespace is the first place to look if the command isn't obvious from the README). You want to see the form config and any JS entry points so you understand what is registered into your Vite build.
4. Read the package's own test suite / demo app. For a form package, the test fixtures are usually the most accurate documentation of the component API — more reliable than the README once a package starts shipping two frontend stacks.

First use case: build a single-field form (one Input) end-to-end — define it in PHP, render it in Vue or React, submit it, and confirm validation errors round-trip back to the component. Do this before reaching for TranslatableInput, because the multi-language field layers extra machinery on top of the same base component and will obscure basic wiring mistakes.

Laravel version note: v1.1.0 adds Laravel 13 compatibility, so both Laravel 12 and 13 should work. Verify your PHP version against the package's composer.json constraint before upgrading either Laravel or the package.

Implementation Patterns

PHP-side definition, frontend-side rendering. Define form schemas as classes or arrays on the PHP side and hydrate them into the Vue/React components. This keeps validation rules, labels, and field structure in one place rather than duplicated across your JS components. Treat the frontend component as a dumb renderer; all policy (required, max length, translatable-or-not) belongs in PHP.

Stack-parallel component tree with a shared contract. Since v1.1.0 ships both Vue and React, the maintainable pattern is to keep your own thin wrapper per stack (e.g. resources/js/components/forms/Input.vue and Input.jsx) that maps your prop conventions onto the package component. When the package fixes a rendering bug or adds a prop, you patch one wrapper per stack instead of every call site.

Validation error wiring. Hook the package's form component into Laravel's standard $errors bag (via Inertia shared props or a useForm-style object). Decide early whether you're using the package's own form-state handling or your framework adapter's — mixing the two is the most common way to get forms that "silently don't show errors."

TranslatableInput as an opt-in layer. Use it for content fields that map to a JSON/translatable column (spatie/laravel-translatable or Laravel's native ->translations() style). Keep it out of forms that only edit non-translatable data: the field carries per-locale state, locale switching UI, and fallback behavior you don't want to pay for on a settings page.

Localization via laravilt/support. v1.1.0 moves the localization composable import to the support package. If you were importing it from a local path or a deep package path, switch to the support package's public export. Centralize the import in one module (resources/js/lib/i18n.js) so a future move of that composable doesn't ripple through every component.

Incremental rollout for existing apps. If you're upgrading from v1.0.x, migrate one form at a time. The v1.1.0 changes are predominantly additive (React stack, translatable field, Laravel 13), but the Vue rendering fixes in PRs #21/#22 change how the Form component renders itself — visually inspect every existing form after upgrade, especially anything on a two-factor / auth page.

Gotchas and Tips

• The two-factor crash is the headline caution. PR #22 fixes "Vue Form rendering itself (two-factor page crash)" — which means v1.0.8 and earlier had a Form component capable of rendering itself recursively under certain slot/parent conditions. After upgrading, test your auth and 2FA pages specifically. If you'd worked around the bug with defensive v-if guards or a wrapper component, revisit and remove them so they don't mask future regressions.
• The React stack is brand new. It landed in the same minor (PR #20) that also added Laravel 13 compat, and PR #21 is a follow-up "fix stability bugs in both the Vue and React stacks." Treat the React path as young: pin an exact version, read the component source when behavior surprises you, and don't assume Vue documentation examples translate directly.
• Dependabot churn is not a feature. Four of the eight changes here are CI action bumps (actions/checkout, softprops/action-gh-release, dependabot/fetch-metadata). They have zero runtime impact — don't read the changelog length as significance, and don't let it distract from the two changes that actually matter (React support, TranslatableInput).
• laravilt/support coupling. The localization composable now comes from a sibling package. If you see a build error like "failed to resolve import" or a missing export after upgrading, check that laravilt/support resolved to a version that actually exports the composable — a stale lockfile is the usual culprit.
• Minor version, but verify semver trust. v1.1.0 is a minor bump, so the maintainers are asserting backwards compatibility. The rendering fixes strain that: behavior changed for anyone who depended on the buggy output. Run your own form test suite (or write a few smoke tests: render → assert no error → submit invalid → assert error visible) before merging into a production branch.
• Debugging rendering issues. When a form renders nothing or renders itself, the fastest signal is usually the browser component tree rather than the PHP side — the PHP payload rarely lies, but slot/prop forwarding in Vue/React does. Log the incoming form schema from PHP first to confirm the data is correct, then work backwards through the component.
• Extension points. Prefer extending through your own wrapper components and PHP form-definition classes over monkey-patching the package's published assets. Published JS assets get overwritten on the next vendor:publish, and this package's frontend has changed enough in one minor release that carrying local patches to its internals will not age well.
• No migration or breaking-change notes in this release. If your upgrade fails, the cause is much more likely to be asset/build-related (stale node_modules, un-republished JS, mismatched support package) than a database schema or API change.