Practical VeeValidate 4 Schema Validation: Correcting Common Integration Patterns

The Reality Check: What Actually Works with VeeValidate 4

After reviewing the integration patterns between VeeValidate 4 and Zod, several critical corrections need to be made to ensure the implementation actually works as expected. The primary issue is package naming: VeeValidate 4 is distributed as @veevalidate/validate, not veevalidate. This matters because the API surface and installation commands differ significantly from the original example.

Corrected Package Installation and Setup

The correct installation command for VeeValidate 4 with Zod integration is:

npm install @veevalidate/validate @veevalidate/zod zod

Note: The @veevalidate/zod adapter package may require checking its current maintenance status, as adapter compatibility can break between major versions.

Verified Implementation Pattern

Here is a corrected implementation that aligns with the actual VeeValidate 4 API:

<script setup>
import { useForm, useField } from '@veevalidate/validate';
import { toTypedSchema } from '@veevalidate/zod';
import * as z from 'zod';

// Define the validation schema
const schema = z.object({
  email: z.string().min(1, 'Email is required').email('Invalid email format'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
  confirmPassword: z.string().min(1, 'Please confirm your password'),
}).refine((data) => data.password === data.confirmPassword, {
  message: "Passwords don't match",
  path: ['confirmPassword'],
});

// Initialize form state
const { errors, handleSubmit, isSubmitting } = useForm({
  validationSchema: toTypedSchema(schema),
  // Note: VeeValidate 4 uses 'lazy' by default for nested object handling
});

// Define fields individually for better control
const [email, emailProps] = useField('email');
const [password, passwordProps] = useField('password');
const [confirmPassword, confirmPasswordProps] = useField('confirmPassword');

const onSubmit = handleSubmit(async (values) => {
  console.log('Form submitted:', values);
});
</script>

<template>
  <form @submit.prevent="onSubmit">
    <div>
      <input v-model="email" v-bind="emailProps" placeholder="Email" />
      <span class="error">{{ errors.email }}</span>
    </div>

    <div>
      <input v-model="password" v-bind="passwordProps" type="password" placeholder="Password" />
      <span class="error">{{ errors.password }}</span>
    </div>

    <div>
      <input v-model="confirmPassword" v-bind="confirmPasswordProps" type="password" placeholder="Confirm Password" />
      <span class="error">{{ errors.confirmPassword }}</span>
    </div>

    <button type="submit" :disabled="isSubmitting">Submit</button>
  </form>
</template>

Key Technical Corrections:

• Package Imports: Must use @veevalidate/validate for the core library and @veevalidate/zod for the adapter.
• useField vs defineField: The correct API for individual field management is useField, not defineField.
• Event Handling: Forms should use @submit.prevent to prevent default form submission behavior.
• Submission State: The isSubmitting flag should be used to prevent duplicate submissions.

Important Limitations and Unknowns

Several aspects of this integration require current verification:

• Adapter Maintenance: The @veevalidate/zod adapter's compatibility with the latest versions of both libraries should be verified before production use.
• Nested Object Handling: VeeValidate 4's handling of deeply nested Zod schemas may require additional configuration that isn't documented in the basic examples.
• Type Inference: The toTypedSchema function's type inference capabilities with complex conditional schemas need validation.

Verification Checklist

To verify this implementation works correctly:

1. Installation: Run npm ls @veevalidate/validate @veevalidate/zod zod to confirm correct versions are installed.
2. Schema Validation: Enter an invalid email format and confirm the error appears after the field loses focus (not immediately on input).
3. Cross-Field Validation: Verify that the password confirmation error only appears after both fields have been touched or the form is submitted.
4. Submission Blocking: Confirm that the submit handler does not execute when required fields are empty.

Trade-offs and Engineering Considerations

When choosing this approach, consider these factors:

• Bundle Size Impact: Adding both VeeValidate and Zod increases bundle size. For simple forms, inline validation might be more appropriate.
• Learning Curve: Team members need familiarity with both Vue's Composition API and schema validation concepts.
• Debugging Complexity: Error paths in nested schemas can be difficult to trace when validation fails.

Actionable Next Steps

Before implementing this pattern in production:

1. Check the @veevalidate/zod package for recent commits and issue activity
2. Create a minimal reproduction to verify the refine() with path option works as expected
3. Test with your specific Vue version (verify Vue 3 compatibility)
4. Profile the validation performance with forms of your typical complexity

Disclaimer: This implementation is based on documented APIs and may require adjustments based on current library versions and specific project requirements.