Better Auth Validation Plugin

1.3.4 · active · verified Wed Apr 22

The `validation-better-auth` package provides a flexible and extensible validation plugin specifically designed for the `better-auth` framework. It enables developers to integrate API request validation using various schema definition libraries such as Zod, Valibot, and ArkType. It also supports Yup by internally wrapping Yup schemas to a standard format. This package is currently at version 1.3.4 and shows an active development cadence with frequent patch releases addressing build, module, and type resolution issues. Its key differentiator is its tight integration with `better-auth` and its adapter pattern, allowing for broad compatibility with different validation schema libraries rather than enforcing a specific one.

Common errors

```
Error: Cannot find module 'validation-better-auth' or its corresponding type declarations.
```
cause Incorrect module resolution due to CommonJS/ESM incompatibility or improper TypeScript configuration.

fix Check your `tsconfig.json` for `module` and `moduleResolution` settings. For modern Node.js, set them to `"NodeNext"` or `"ESNext"`. Ensure your build process transpiles correctly if targeting older environments.
```
TypeError: validator is not a function
```
cause Attempting to `require()` the package in a CommonJS context without proper interop or when the package is primarily ESM.

fix Switch to ESM import syntax: `import { validator } from 'validation-better-auth'`. If forced to use CommonJS, ensure your bundler (e.g., Webpack, Rollup) is configured to handle ESM interop correctly, or transpile your code.
```
Plugin validation failed: Expected schema property or adapter property to be defined.
```
cause A validation entry in the `validator` plugin array is missing either the `schema` property (for standard schemas) or the `adapter` property (for custom/wrapped schemas).

fix For each object in the `validator` plugin array, ensure it has either `schema: YourSchemaInstance` or `adapter: YourAdapter(YourSchemaInstance)` defined for the specific `path`.

Warnings

gotcha Multiple patch releases (v1.3.4, v1.3.3, v1.3.2, v1.3.1) have addressed module resolution and build issues related to ESM and CommonJS. Developers should ensure their build setup correctly handles module imports.
Fix: Ensure your `tsconfig.json` and build tools are configured for modern module resolution (e.g., `"module": "NodeNext"`, `"moduleResolution": "NodeNext"`) and verify imports are using ESM syntax for recent Node.js versions.
gotcha The package relies on `better-auth` as a peer dependency. Mismatched major versions between `validation-better-auth` and `better-auth` could lead to unexpected behavior or runtime errors.
Fix: Always install `better-auth` and `validation-better-auth` such that their peer dependency ranges are satisfied. Check the `package.json` for compatible versions.
gotcha While the package supports various schema libraries via adapters (e.g., YupAdapter), using a 'Standard Schema' directly (e.g., Zod, Valibot) might offer a more streamlined experience without the overhead of an adapter layer.
Fix: For new projects, consider using a 'standard' schema library like Zod or Valibot to leverage direct integration. If using Yup, ensure `YupAdapter` is correctly imported and applied.

Install

npm install validation-better-auth npm
yarn add validation-better-auth yarn
pnpm add validation-better-auth pnpm

Imports

validator
wrong:
```
const { validator } = require('validation-better-auth')
```
correct:
```
import { validator } from 'validation-better-auth'
```
Primarily designed for ESM usage in modern Node.js environments. CommonJS `require` might work with transpilation, but ESM imports are canonical.
StandardAdapter
```
import { StandardAdapter } from 'validation-better-auth'
```
Used when explicitly working with the internal standard schema adapter or if custom adapters need to extend it.
YupAdapter
```
import { YupAdapter } from 'validation-better-auth'
```
This adapter is required to integrate Yup schemas into the validation plugin configuration.

Quickstart

This quickstart demonstrates how to integrate the `validation-better-auth` plugin into the `better-auth` framework, using Zod schemas for request body validation on specific API paths, including `before` and `after` hooks.

import { betterAuth } from "better-auth";
import { validator, StandardAdapter } from "validation-better-auth";
import { z } from 'zod'; // Assuming Zod is used for SignupSchema and SignInSchema

// Define your schemas (e.g., using Zod)
const SignupSchema = z.object({
    email: z.string().email(),
    password: z.string().min(8),
    confirmPassword: z.string()
}).refine(data => data.password === data.confirmPassword, {
    message: "Passwords don't match",
    path: ["confirmPassword"],
});

const SignInSchema = z.object({
    email: z.string().email(),
    password: z.string().min(8)
});

export const auth = betterAuth({
    appName: "My Validation App",
    plugins: [
        validator(
            [
                {
                    path: "/sign-up/email",
                    schema: SignupSchema,
                    before: (ctx) => {
                        console.log('Before signup validation:', ctx.payload);
                    },
                    after: (ctx) => {
                        console.log('After signup validation:', ctx.payload);
                    }
                },
                {
                    path: "/sign-in/email",
                    schema: SignInSchema,
                    before: (ctx) => {
                        console.log('Before signin validation:', ctx.payload);
                    },
                    after: (ctx) => {
                        console.log('After signin validation:', ctx.payload);
                    }
                }
            ]
        )
    ]
});

// In a real application, 'auth' would then be used to configure your authentication routes.
// For demonstration, we'll just log its presence.
console.log('Better Auth instance configured with validation plugin.');

view raw JSON →