Nuxt Yup

A Nuxt module that brings Yup into your app with first-class Nuxt integration, global access, and typed extension support.

Features

• 🔌  Use Yup anywhere with the auto-imported useYup() composable
• 🌍  Configure global validation messages through app.config.ts
• 📦  Add custom methods from yup.methods.ts
• 🏷️  Automatically generate TypeScript types for custom Yup methods

Why use nuxt-yup?

nuxt-yup gives you a Nuxt-native Yup workflow with minimal setup.

• Auto-imported useYup() composable
• Global configuration through app.config.ts
• Typed custom Yup extensions
• Seamless Nuxt runtime integration
• Better DX with less boilerplate

Quick Example

const yup = useYup()

const userSchema = yup.object({
  name: yup.string().required(),
  email: yup.string().email().required(),
  document: yup.string().cnpj(), // custom method from yup.methods.ts
})

const sampleUser = {
  name: 'Ada Lovelace',
  email: '[email protected]',
  document: '12345678901234',
}

await userSchema.validate(sampleUser)

Quick Setup

Install the module in your Nuxt project:

npx nuxi@latest module add nuxt-yup

Yup is now available globally in your app.

Usage

Access Yup anywhere with useYup() or the $yup plugin.

<template>
  <div>
    <input v-model="value" placeholder="Enter a value" />
    <p>Is valid: {{ isValid }}</p>
  </div>
</template>

<script setup>
const yup = useYup()
// or: const { $yup } = useNuxtApp()

const value = ref('')
const isValid = ref(false)

const schema = yup.string().min(3).required()

watch(value, async (newValue) => {
  isValid.value = await schema.isValid(newValue)
})
</script>

Comparison

| Feature | Yup | nuxt-yup | |---|---|---| | Auto-import composable | Manual import and wiring | useYup() available automatically | | Global config | Manual setup in app bootstrap | Configure with app.config.ts | | Typed extensions | Manual declaration merging | Typed descriptors + generated augmentation | | Nuxt developer experience | Generic library usage | Nuxt-first integration and DX |

Configuration

Customizing error messages (setLocale)

Override Yup default messages globally with yup.setLocale in app.config.ts.

// app.config.ts
export default defineAppConfig({
  yup: {
    setLocale: {
      mixed: {
        required: 'This field is required',
      },
      string: {
        min: 'Must be at least ${min} characters',
        email: 'Must be a valid email address',
      },
      number: {
        min: 'Must be at least ${min}',
        max: 'Must be at most ${max}',
      },
    },
  },
})

See the full list of keys in the Yup locale documentation.

Module options (nuxt.config.ts)

Use methodsDir when your methods file is outside the Nuxt root.

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-yup'],
  yup: {
    methodsDir: './shared/validation',
  },
})

• The module searches this directory for yup.methods.*.
• If no file is found, it logs an error and continues without custom methods.

yup.methods.ts

Create a yup.methods.ts file in your project root to register custom methods. The module auto-detects it and supports two modes.

Typed Mode — defineYupExtension (recommended)

Export an array of descriptors with defineYupExtension. Type augmentations are generated automatically.

// yup.methods.ts
import { defineYupExtension } from 'nuxt-yup'

export default defineYupExtension([
  {
    name: 'cnpj',
    type: 'string',
    message: 'Invalid CNPJ',
    validate(value: string) {
      return /^\d{14}$/.test(value)
    },
  },
  {
    name: 'isEven',
    type: 'number',
    message: 'Must be an even number',
    async validate(value: number) {
      return value % 2 === 0
    },
  },
])

Each descriptor accepts:

| Property | Type | Description | |---|---|---| | name | string | Method name to add to the schema | | type | YupExtensionType | Yup schema type to extend | | message | string (optional) | Default error message | | validate | (value) => boolean \| Promise<boolean> | Validation logic (sync or async) |

Yup types are automatically augmented, so you get full autocomplete:

// ✅ TypeScript knows about .cnpj() and .isEven()
useYup().string().cnpj()
useYup().number().isEven()

Compat Mode — function export

For full control (for example, migrations from an existing setup), export a function that receives the yup instance directly. Type augmentations are not generated in this mode.

// yup.methods.ts
import type * as Yup from 'yup'

export default function extendYup(yup: typeof Yup) {
  yup.addMethod(yup.StringSchema, 'documentId', function (message = 'Invalid document') {
    return this.test('document-id', message, (value) => {
      if (value == null) return true
      return typeof value === 'string' && value.length >= 6
    })
  })
}

Supported file extensions

The yup.methods file is resolved in this order from your project root (or from methodsDir):

.ts → .mts → .cts → .js → .mjs → .cjs

Works well with

• Nuxt 3 / Nuxt 4
• TypeScript
• vee-validate
• Nuxt server routes (server/api/*)

Contributing

Contributions are welcome. Open an issue for bugs or feature ideas, and submit a PR when you're ready.

For local development and test commands, see package.json.

License

MIT — Made with ❤️ by Darlan Prado