Laravel Precognition for Vue 3

Common errors

• TypeError: Cannot read properties of undefined (reading 'errors') at useForm

  cause The `useForm` function expects a method, URL, and initial data object. Providing `undefined` or an invalid structure for the initial data can cause this.
  fix Ensure `useForm` is called with the correct signature: `useForm('post', '/api/endpoint', { field1: '', field2: '' })` where the third argument is an object of initial form data.

• Uncaught ReferenceError: useForm is not defined

  cause The `useForm` composition function was not imported from `laravel-precognition-vue`.
  fix Add `import { useForm } from 'laravel-precognition-vue';` to your script section or component setup.

• Failed to load resource: the server responded with a status of 422 (Unprocessable Content) - network error in browser console without specific validation messages

  cause The Laravel backend is returning validation errors, but the browser's developer console is showing a generic network error without the detailed validation messages, likely due to a missing or incorrect `Accept` header which prevents Precognition from intercepting the validation response.
  fix Ensure the `Accept` header is set to `application/json` for Precognition requests. Version 2.0.0 and later automatically set this header, but for custom `fetch` implementations or older versions, verify this header is present.

Warnings

• breaking Version 2.0.0 replaced Axios with the native `fetch` API for all HTTP requests. This means any custom Axios configurations, interceptors, or adapters will no longer function. Developers must adapt their code to use `fetch`-compatible patterns or provide their own `fetch` wrapper.
  Fix: Migrate any Axios-specific logic to use the native `fetch` API. If custom HTTP client behavior is required, consider wrapping the `fetch` API or providing a custom client function to `useForm` if the package supports it (check documentation for `client` option).
• breaking When upgrading from `laravel-precognition` (the core package) versions prior to v1.0.0, be aware that support for Inertia packages was removed. While `laravel-precognition-vue` is a specific integration, ensure your project setup is not relying on older core package features related to Inertia.
  Fix: For Inertia applications, use the dedicated `laravel-precognition-vue-inertia` package if available, or ensure your integration strategy aligns with the current package's scope as a standalone Vue client.
• gotcha Prior to v1.0.1, TypeScript support for wildcard validation paths (e.g., `data.*.name`) could be inconsistent. This might lead to type errors or incorrect inference when accessing errors for deeply nested or dynamic fields.
  Fix: Upgrade to v1.0.1 or newer to benefit from improved TypeScript support for wildcard validation paths. Ensure your `Form` type definitions accurately reflect your backend validation structure.
• gotcha Files uploaded via `form.setFile()` or similar methods are not automatically validated unless `disableFileValidation()` is explicitly enabled. If file validation is crucial, ensure it's properly configured.
  Fix: From v0.8.0, the `disableFileValidation()` method was added. If using older versions, manual validation or a custom approach for files might be necessary. For newer versions, ensure you understand how file validation is triggered and managed by Precognition.

Install

• npm install laravel-precognition-vue npm
• yarn add laravel-precognition-vue yarn
• pnpm add laravel-precognition-vue pnpm

Imports

• useForm
  wrong:

  import useForm from 'laravel-precognition-vue'

  correct:

  import { useForm } from 'laravel-precognition-vue'

  The primary composition function for creating Precognition-enabled forms. It is a named export.
• Form
  wrong:

  import { Form } from 'laravel-precognition-vue'

  correct:

  import type { Form } from 'laravel-precognition-vue'

  Type definition for the form object returned by `useForm`. Use `import type` for type-only imports in TypeScript.
• Precognition errors and validation
  wrong:

  import { validate } from 'laravel-precognition-vue'

  correct:

  import { useForm } from 'laravel-precognition-vue';
  const form = useForm(...);
  form.validate('field');
  form.errors.field;

  Validation methods and error state are properties of the `form` object returned by `useForm`, not separate exports.

Quickstart

This quickstart demonstrates how to set up a simple registration form using `useForm` for live validation. It shows binding form data, triggering validation on input, displaying errors, and submitting the form. The example includes basic error handling and form reset functionality.

import { defineComponent, reactive } from 'vue';
import { useForm } from 'laravel-precognition-vue';

export default defineComponent({
  setup() {
    const form = useForm('post', '/api/register', {
      name: '',
      email: '',
      password: '',
      password_confirmation: '',
    });

    const submit = async () => {
      try {
        await form.submit();
        alert('Registration successful!');
        form.reset();
      } catch (e) {
        console.error('Submission failed:', e);
        // Errors are automatically populated in form.errors
      }
    };

    // Example of real-time validation on input change
    const validateField = (field) => {
      if (form[field]) { // Only validate if field has content
        form.validate(field);
      }
    };

    return { form, submit, validateField };
  },
  template: `
    <form @submit.prevent="submit">
      <div>
        <label for="name">Name</label>
        <input id="name" type="text" v-model="form.name" @input="validateField('name')">
        <div v-if="form.errors.name">{{ form.errors.name }}</div>
      </div>

      <div>
        <label for="email">Email</label>
        <input id="email" type="email" v-model="form.email" @input="validateField('email')">
        <div v-if="form.errors.email">{{ form.errors.email }}</div>
      </div>

      <div>
        <label for="password">Password</label>
        <input id="password" type="password" v-model="form.password" @input="validateField('password')">
        <div v-if="form.errors.password">{{ form.errors.password }}</div>
      </div>

      <div>
        <label for="password_confirmation">Confirm Password</label>
        <input id="password_confirmation" type="password" v-model="form.password_confirmation" @input="validateField('password_confirmation')">
        <div v-if="form.errors.password_confirmation">{{ form.errors.password_confirmation }}</div>
      </div>

      <button type="submit" :disabled="form.processing">Register</button>
      <button type="button" @click="form.reset()">Reset</button>
    </form>
  `
});