Getting started

You may install VineJS inside an existing Node.js project from the npm packages registry.

npm i @vinejs/vine

yarn add @vinejs/vine

pnpm add @vinejs/vine

Once installed, you can import and use VineJS as follows.

import vine from '@vinejs/vine'

const schema = vine.object({
  username: vine.string(),
  email: vine.string().email(),
  password: vine
    .string()
    .minLength(8)
    .maxLength(32)
    .confirmed()
})

const data = {
  username: 'virk',
  email: 'virk@example.com',
  password: 'secret',
  password_confirmation: 'secret',
}

const output = await vine.validate({
  schema,
  data
})

console.log(output)

• The vine.object method defines the top-level object for the validation schema.

• The validation is performed using the validate method. The validate method accepts the schema and the data object to perform the validation.

• If validation passes, the return value will be a new object with validated properties.

• If validation fails, an exception will be raised.

Pre-compiling schema

The performance benefits of using VineJS kick in when you pre-compile a schema. During the pre-compile phase, VineJS will convert your schema into an optimized JavaScript function that you can reuse to perform validations.

You may pre-compile a schema using the vine.compile method. The compile method returns a validator object you must use to perform validations.

import vine from '@vinejs/vine'

const schema = vine.object({
  username: vine.string(),
  email: vine.string().email(),
  password: vine
    .string()
    .minLength(8)
    .maxLength(32)
    .confirmed()
})

const data = {
  username: 'virk',
  email: 'virk@example.com',
  password: 'secret',
  password_confirmation: 'secret',
}

const validator = vine.compile(schema)
const output = await validator.validate(data)

console.log(output)

You may pass a custom messages provider or error reporter as the second argument to the validator.validate method.

const validator = vine.compile(schema)
const output = await validator.validate(data, {
  messagesProvider,
  errorReporter,
  meta: {}
})

Handling errors

In case of an error, VineJS will throw a ValidationError exception. You may access the detailed error messages using the error.messages property.

import vine, { errors } from '@vinejs/vine'

try {
  const validator = vine.compile(schema)
  const output = await validator.validate(data)
} catch (error) {
  if (error instanceof errors.E_VALIDATION_ERROR) {
    console.log(error.messages)
  }
}

The error.messages property is an array of error objects with the following properties.

• field - The name of the field under validation. Nested fields are represented with a dot notation. For example: contact.email.
• message - Error message.
• rule - The rule that reported the error.
• index? - Array element index for which the validation failed.
• meta? - Optional meta-data set by the validation rule when reporting the error.

Custom error messages

Error messages workflow in VineJS is managed using the messages provider. VineJS ships with a simple messages provider that accepts error messages for validation rules or a field + rule combination.

Learn more about custom error messages.

Formatting errors

VineJS uses error reporters to change the formatting of error messages. For example, if you follow the JSON API spec, you may create an error reporter that formats the errors per the spec.

Learn more about error reporters.

Inferring types from schema

The validate method output is fully typed; hence, you do not have to perform manual type inference.

However, if you want to infer types directly from the schema (without performing validation), you may use the Infer type helper. For example:

import vine from '@vinejs/vine'
import { Infer } from '@vinejs/vine/types'

const schema = vine.object({
  username: vine.string(),
  email: vine.string().email(),
  password: vine
    .string()
    .minLength(8)
    .maxLength(32)
    .confirmed()
})

type UserRegistration = Infer<typeof schema>
/**
 * {
 *   username: string
 *   email: string
 *   password: string
 * }
 */

Infer input types

You can infer the input data accepted by your schema using the InferInput type helper.

import vine from '@vinejs/vine'
import { InferInput } from '@vinejs/vine/types'

const schema = vine.object({
  username: vine.string(),
  email: vine.string().email(),
  is_admin: vine.boolean(),
  password: vine
    .string()
    .minLength(8)
    .maxLength(32)
})

type UserRegistrationInput = InferInput<typeof schema>
/**
 * {
 *   username: string
 *   email: string
 *   is_admin: boolean | string | number
 *   password: string
 * }
 */