eslint-plugin-valibot

ESLint rules for safer, more maintainable Valibot usage.

eslint-plugin-valibot helps catch common schema mistakes and patterns that make Valibot code harder to maintain.

The plugin ships with both flat-config and legacy-config presets, plus individual rules that you can enable as needed.

Rules

💼 Configurations enabled in.
⚠️ Configurations set to warn in.
✅ Set in the recommended configuration.
🔒 Set in the strict configuration.
🎨 Set in the stylistic configuration.
🔧 Automatically fixable by the --fix CLI option.

| Name                                 | Description | 💼 | ⚠️ | 🔧 | | :----------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ | :--- | :--- | :- | | consistent-import | Enforce a consistent Valibot import style using either namespace or named imports. | | 🎨 | | | consistent-schema-convention | Enforce a consistent Valibot schema naming convention for exported schemas and inferred types. | | 🎨 | | | no-any-schema | Disallow Valibot any() schemas. | | 🔒 | | | no-duplicate-pipe-actions | Disallow duplicate Valibot actions inside the same pipe() call. | | ✅ 🔒 | 🔧 | | no-empty-pipe | Disallow empty pipe() calls or pipe() calls with a single argument. | ✅ 🔒 | | 🔧 | | no-instanceof-builtins | Prefer primitive schema functions over instance(Constructor) for built-in types. | ✅ 🔒 | | 🔧 | | no-loose-object | Disallow disallowed Valibot object schema constructors such as looseObject(). | | 🔒 | | | no-recreated-schemas | Disallow recreating static Valibot schemas inside function scope. | | 🔒 | | | no-redundant-schema-wrappers | Disallow redundant nested Valibot schema wrappers. | ✅ 🔒 | | 🔧 | | no-redundant-transformation | Disallow redundant manual transformations that duplicate built-in Valibot actions. | | ✅ 🔒 | 🔧 | | no-schema-as-type | Disallow using a Valibot schema value itself as a TypeScript type. | 🔒 | | | | no-transform-in-record-key | Disallow transforms in record() key schemas, which can silently mutate keys and cause collisions. | ✅ 🔒 | | | | no-unguarded-parse | Require Valibot parse() and assert() calls to be wrapped in try/catch. | ✅ 🔒 | | | | no-unknown-schema | Disallow Valibot unknown() schemas. | | 🔒 | | | prefer-nullable-over-union-null | Prefer nullable() over union([schema, null()]) when they are equivalent. | | ✅ 🔒 | 🔧 | | prefer-nullish | Prefer nullish() over nested optional() and nullable() wrappers. | | ✅ 🔒 | 🔧 | | prefer-optional-over-union-undefined | Prefer optional() over union([schema, undefined()]) when they are equivalent. | | ✅ 🔒 | 🔧 | | prefer-picklist | Prefer picklist() over union() when the union only contains literal string schemas. | | 🎨 | 🔧 | | prefer-variant | Prefer variant() over union() when object schemas share an obvious discriminant key. | | 🎨 | 🔧 | | require-issue-messages | Require explicit custom issue messages on Valibot schemas and issue-producing actions. | | 🔒 | |

Every rule has its own documentation page under docs/rules.

Installation

pnpm add -D eslint-plugin-valibot

It is designed for eslint@^9 || ^10 and valibot@^1.

Flat Config

import { defineConfig } from 'eslint/config';
import js from '@eslint/js';
import valibot from 'eslint-plugin-valibot';

export default defineConfig(
  js.configs.recommended,
  ...valibot.flatConfigs.recommended,
);

Use valibot.flatConfigs.strict for the stricter preset, or append ...valibot.flatConfigs.stylistic if you also want the naming-style rule.

Legacy Config

module.exports = {
  extends: ['plugin:valibot/recommended'],
};

Available legacy presets are:

• plugin:valibot/recommended
• plugin:valibot/strict
• plugin:valibot/stylistic

TypeScript Projects

If you lint TypeScript, compose this plugin with typescript-eslint. The strict preset includes valibot/no-schema-as-type, which only applies to TypeScript syntax.

import tseslint from 'typescript-eslint';
import valibot from 'eslint-plugin-valibot';

export default tseslint.config(
  ...tseslint.configs.recommended,
  ...valibot.flatConfigs.strict,
);

Config Presets

| Preset | Intended use | Notes | | :------------ | :----------------------------------------------------- | :------------------------------------------------------------------------- | | recommended | Good default for most codebases | Focuses on common correctness and safety issues. | | strict | Tighter policy for teams that want broader enforcement | Includes everything in recommended plus stricter schema usage checks. | | stylistic | Naming consistency | Adds naming-convention rules without changing the problem-focused presets. |

See docs/configs.md for the exact rule list in each preset.

Individual Rules

If you prefer to enable rules one by one, register the plugin and configure only the rules you want:

import { defineConfig } from 'eslint/config';
import valibot from 'eslint-plugin-valibot';

export default defineConfig({
  plugins: {
    valibot,
  },
  rules: {
    'valibot/no-unguarded-parse': 'error',
    'valibot/prefer-nullish': 'warn',
  },
});

Examples

Working example setups live in this repository:

• examples/flat
• examples/legacy
• examples/typescript

The default flat and legacy examples use the recommended preset. The flat example directory also includes dedicated strict and stylistic config files for stricter or naming-focused setups.

Contributing

Contributor setup, checks, and rule authoring workflow live in CONTRIBUTING.md.