Inertia Routes Laravel Package

Getting Started

This package wraps Inertia form handling in a composable that gives you a single object for state, submission, and server-driven defaults. You get form.get/post/put/patch/delete, a submit escape hatch, per-call visit options, and a resetOnSuccess behaviour that keeps your create forms clean after a redirect.

Minimal setup:

1. Install and register. Install the package alongside Inertia (inertiajs/inertia-laravel + your client adapter), then register the plugin/composable the way the package docs specify. There is usually a config file for defaults (hydration behaviour, reset behaviour) — publish it once so you can see what's tunable.
2. Wire the meta endpoint. The "meta request" is what hydrates form defaults from the server (e.g. a create action returning initial values). Confirm the route/controller the package expects exists and returns a props payload your form can hydrate from. If you use autoHydrate: false, skip this until you need it.
3. First use case: a create form. Build one resource with useForm({...defaults}), bind fields to form.data, and call form.post(route('posts.store')) with resetOnSuccess: true. Handle the redirect in your Laravel controller (redirect()->route('posts.index')) and let Inertia do the rest. This exercises the whole loop — defaults, submit, validation errors, reset — in about 30 lines.
4. Where to look first. The composable's options object (that's where visitOptions, resetOnSuccess, and hydration flags live), then your controller's create/store pair, then the package's release notes for the 4.x line since several v4.5.6 fixes changed callback ordering and reset semantics.

If a form doesn't hydrate, check the meta endpoint before you touch the composable — nine times out of ten it's a props shape mismatch on the Laravel side, not a client bug.

Implementation Patterns

Two-layer callbacks: shared and per-call. Since v4.5.6, onSuccess in visitOptions and a per-call onSuccess both run — shared first, then per-call. Use the shared one for cross-cutting concerns (toasts, analytics, closing a drawer) and the per-call one for page-specific side effects:

const form = useForm({
  name: '',
  visitOptions: {
    onSuccess: () => toast.success('Saved'),
  },
});

form.post(route('posts.store'), {
  onSuccess: (page) => router.visit(page.props.redirectTo),
});

Don't duplicate work across both layers — the shared handler already fired by the time the per-call one runs.

Read submitted data in onSuccess before reset. onSuccess now receives the page and is awaited, and it runs before resetOnSuccess clears the form. That makes this the correct place to snapshot what the user submitted (draft recovery, optimistic UI, "you just created X" messaging):

form.post(route('posts.store'), {
  resetOnSuccess: true,
  onSuccess: (page) => {
    lastSubmitted.value = { ...form.data }; // still populated
  },
});

Async callbacks are awaited. Because onSuccess is awaited, you can await a fetch, a modal confirmation, or a router.reload() inside it and the reset will not race you. Keep these short — a slow callback holds up the reset and any chained visit behaviour.

Backend contract stays boring. Keep Laravel controllers conventional: validate with a FormRequest, return redirect()->back()->withErrors() on failure, redirect()->route(...) on success. The package maps validation errors onto form.errors and reads form.processing; you should not need custom error plumbing. Use ->with('success', ...) flash plus shared Inertia props if you want feedback to survive the redirect.

Per-call visit options for one-off behaviour. preserveScroll, headers, onError, only, etc. belong in the per-call object when they differ between submits. v4.5.6 fixed leaking, so per-call options no longer bleed into the next submit — which means you can now safely do form.put(url, { preserveScroll: true }) on one button and a plain form.put(url) on another in the same component without ordering surprises.

Choose reset strategy per form, not globally. resetOnSuccess: true is right for "create another" flows and wrong for edit forms where the user expects their values to persist. For edit screens, either disable it or reset to a server-refreshed snapshot after the redirect.

Hydration patterns. Let the meta request hydrate for edit forms (server is the source of truth). For create forms where defaults are static, pass a plain object — but see the nested-object caveat below if you rely on reset.

submit as the escape hatch. When you need to branch on intent (save vs. publish) inside one handler, form.submit(method, url, options) keeps a single submit path instead of three near-identical handlers.

Gotchas and Tips

Reset and nested data. Before v4.5.6, the reset snapshot shared nested arrays and objects with the live form — mutating a nested value after reset could poison the snapshot. If you're on an older 4.x, upgrade before trusting resetOnSuccess on forms with arrays or object fields. On 4.5.6+, defaults are deep-copied; still prefer immutable field updates over in-place mutation of form.data.items[i] so your own code doesn't reintroduce the aliasing.

Reset without hydration. resetOnSuccess now falls back to the form's own defaults when no hydrated snapshot exists — data passed as a function, autoHydrate: false, or a submit that beats the meta request home. This fixed a real class of "reset clears to empty" bugs, but it means the reset target depends on when you submit. If a form must always reset to server values, disable submit until hydration completes (form.processing || hydrating) rather than relying on the fallback.

Options object mutation. v4.5.6 stopped mutating caller-supplied options objects. If you were (accidentally) relying on the package writing back into a shared options constant, that behaviour is gone — build a fresh object per call. Conversely, if you saw weird cross-form effects from a shared constant, this release fixes it.

Repeated callbacks. The extra onSuccess wrapper stacking on every submit is fixed. Symptom to watch for on older versions: toasts firing N times where N is the number of submits in the session — a classic "works in dev, triples in production after a few edits" bug.

form.post() with no arguments. Calling form.post() or form.post(url) no longer throws while resetOnSuccess is enabled. If you have defensive wrappers around argument-less submits, you can remove them.

Array defaults and prefix collisions. Array field defaults previously mis-typed when a sibling field shared a prefix (items vs items_count). If you have fields whose names prefix each other, upgrade and re-verify the initial shape — and name fields to avoid the collision in the first place (items / itemsCount vs items / items_count is fine now, but prefixes are still a smell).

Debugging order of operations. When success behaviour looks wrong, log in this order: visitOptions.onSuccess → per-call onSuccess → resetOnSuccess. Knowing the reset runs last explains most "my callback saw empty data" reports. Add temporary console.log in both handlers; the sequence is the diagnostic.

Extension points. The composable options object is the intended seam: wrap useForm in your own useResourceForm that injects your visitOptions defaults (toasts, error reporting, preserveState) and a standard resetOnSuccess policy. That keeps the two-layer callback contract consistent across the app and gives you one place to change when the next 4.x release adjusts ordering again.

Pin the minor. Several fixes here are behavioural (callback ordering, reset-to-defaults, no-mutation). Pin ^4.5.6 and read the notes before jumping minors; anything touching onSuccess ordering is exactly the kind of change that silently breaks a drawer-close or redirect that used to run last.