Inertia, Laravel and Vue

Inertia & Laravel Integration

Align Laravel server responses, Inertia navigation, validation errors and local Vue UI state into a seamless single-page experience.

1. Check the installed @inertiajs/vue3 version first

• Inspect package.json and composer.json (inertiajs/inertia-laravel):
  • Inertia v2 adds <Form>, <Deferred>, <WhenVisible>, usePoll, prefetching (<Link prefetch>) and Inertia::optional() / Inertia::defer() / Inertia::merge().
  • Inertia v1 uses useForm, <Link>, router and Inertia::lazy() without <Deferred> or <Form>. Never use v2-only components in a v1 project.

2. Page props, shared data and state ownership

• Treat Inertia page props as server-owned state passed from the Laravel controller (Inertia::render()). Define a typed defineProps<PageProps>() contract matching the controller's payload and API resources.
• Access global shared data (authenticated user, flash messages, permissions, locale) via const page = usePage<SharedProps>() and derive reactive values with computed(() => page.props.auth.user).
• Never mutate page props directly. When a user edits server data locally, initialize a useForm(...) or local draft ref, and decide deliberately when a fresh prop update should reset or preserve the local draft.
• Remember that hiding a button in Vue based on page.props.can is UX convenience only; real authorization lives in Laravel Policies/Gates on the server.

3. Navigation, partial reloads and deferred data

• Use <Link :href="..."> (or <Link as="button" method="post">) for internal navigation instead of raw <a href> tags that trigger full page reloads, and router.visit() / router.get() for programmatic navigation.
• For filter/search/sort bars driven by the server, use router.get(url, filters, { preserveState: true, preserveScroll: true, replace: true, only: ['items', 'filters'] }), debouncing text inputs and canceling stale visits Automatically via Inertia's built-in visit cancellation.
• Use partial reloads (only: ['stats'] or except: [...]) to refresh specific props without re-executing heavy queries when the server wraps expensive props in fn () => ... or Inertia::optional().
• In Inertia v2, wrap deferred controller props (Inertia::defer(...)) in <Deferred data="permissions"><template #fallback>...</template>...</Deferred> with a skeleton fallback so the initial page renders immediately.

4. Forms, validation errors and submission feedback

• Use useForm({ ... }) (or Inertia v2's <Form> component where matches project conventions) for mutations (form.post, form.put, form.patch, form.delete):
  • Bind submit buttons to :disabled="form.processing" to prevent double submissions and show progress feedback.
  • Display server validation errors inline via form.errors.field (aria-invalid, aria-describedby), and clear or reset fields deliberately in onSuccess: () => form.reset() (or preserveScroll: true on error).
  • Use form.isDirty to warn before discarding unsaved changes, and pass a unique remember key (useForm('EditProject:' + props.project.id, { ... })) when form state should survive back/forward history navigation.

Before you finish

• Verified @inertiajs/vue3 version (v1 vs v2) and matched the project's route helper convention (Wayfinder, Ziggy route() or explicit URLs).
• Page props and usePage() shared data are typed and never mutated directly.
• Forms handle form.processing, inline form.errors, preserveScroll and post-success reset/feedback cleanly.
• preserveState and preserveScroll are chosen deliberately for the user's workflow.