DEV Community: Ciprian Toma

5 Zod refinements you keep rewriting (and how to stop)

Ciprian Toma — Mon, 27 Apr 2026 13:28:10 +0000

Every project starts the same way. You set up Zod, define your form schema, and then spend the next hour writing .refine() chains for fields you've validated a hundred times before.

Email with disposable domain blocking. Password with uppercase, digits, special characters and length. Phone numbers that need to be E.164. Usernames that can't be "admin" or "root". IBAN that passes the mod-97 check.

You've written all of these before. So have I. At some point I got tired of copy-pasting the same 40-line refinement block into every new project, so I extracted them into a library.

Here are the 5 I was rewriting most often, what they look like in raw Zod, and what I replaced them with.

1. Email validation (with disposable domain blocking)

The basic check is easy. The edge cases aren't.

// raw Zod
const email = z.string()
  .email()
  .refine(val => !val.endsWith('+'), 'No plus aliases')
  .refine(val => {
    const domain = val.split('@')[1]
    return !disposableDomains.includes(domain)
  }, 'Disposable email not allowed')

Where does disposableDomains come from? You either maintain a list yourself, pull one from npm, or skip it entirely because it's too much hassle. And you still haven't handled plus-aliasing properly.

// validex
const email = Email({
  blockDisposable: true,
  blockPlusAlias: true
})

One line. Disposable list is built in via disposable-email-domains-js. Plus-alias detection included. Returns a standard Zod schema. Error codes: email.invalid, email.disposableBlocked, email.plusAliasBlocked.

2. Password strength

This one always balloons. Every form has slightly different requirements, and every .refine() produces the same generic "custom" error code.

// raw Zod
const password = z.string()
  .min(8, 'At least 8 characters')
  .max(64, 'Max 64 characters')
  .refine(val => /[A-Z]/.test(val), 'Need an uppercase letter')
  .refine(val => /[a-z]/.test(val), 'Need a lowercase letter')
  .refine(val => /[0-9]/.test(val), 'Need a digit')
  .refine(val => /[^A-Za-z0-9]/.test(val), 'Need a special character')
  .refine(val => !/(.)\1{3,}/.test(val), 'No more than 3 consecutive repeated characters')

7 lines. Every error is code: "custom". Good luck building a password strength meter from that.

// validex
const password = Password({
  length: { min: 8, max: 64 },
  uppercase: { min: 1 },
  lowercase: { min: 1 },
  digits: { min: 1 },
  special: { min: 1 },
  consecutive: { max: 3 }
})

Same validation. But each check has its own error code: password.minUppercase, password.minLowercase, password.minDigits, password.minSpecial, password.maxConsecutive. You can map those directly to UI feedback or i18n keys without parsing strings.

Also supports blockCommon with three tiers: 'basic' (top 100), 'moderate' (top 1,000), or 'strict' (top 10,000 passwords from real breach data).

3. Phone numbers

Phone validation is deceptively hard. Most devs reach for a regex and hope for the best.

// raw Zod
const phone = z.string()
  .refine(val => /^\+[1-9]\d{6,14}$/.test(val), 'Invalid E.164 format')

This passes +1234567, which is technically E.164 compliant but not a real phone number. It also rejects valid numbers with spaces or dashes that users naturally type.

// validex
const phone = Phone()

Validates via libphonenumber-js under the hood. Normalises output to E.164 by default. You can also restrict by country, require mobile numbers, or require a country code prefix. Error code: phone.invalid.

4. Username

Looks simple until you realise you need to block reserved words, check character sets, and handle edge cases like consecutive dots or leading underscores.

// raw Zod
const username = z.string()
  .min(3)
  .max(20)
  .regex(/^[a-zA-Z0-9_]+$/, 'Only letters, numbers, underscores')
  .refine(val => !['admin', 'root', 'system', 'moderator', 'null', 'undefined']
    .includes(val.toLowerCase()), 'Reserved username')

Your reserved list is always incomplete. You add to it every time someone signs up as "administrator" or "support".

// validex
const username = Username({
  length: { min: 3, max: 20 },
  blockReserved: true
})

Built-in reserved word list. Error codes: username.invalid, username.reservedBlocked, username.boundary.

5. IBAN

This one is wild. Most devs skip it or use a separate library just for this field.

// raw Zod - good luck
const iban = z.string()
  .refine(val => {
    const rearranged = val.slice(4) + val.slice(0, 4)
    const numeric = rearranged.replace(/[A-Z]/g, c =>
      (c.charCodeAt(0) - 55).toString()
    )
    let remainder = ''
    for (const char of numeric) {
      remainder = String(Number(remainder + char) % 97)
    }
    return Number(remainder) === 1
  }, 'Invalid IBAN')

That's the mod-97 check. You still need to validate country code, length per country, and format.

// validex
const iban = Iban()

One line. Mod-97 check, country-specific length and format validation. Error codes: iban.invalid, iban.countryBlocked, iban.countryNotAllowed.

The pattern

Every rule returns a standard Zod schema. You compose them with z.object() like anything else:

import { z } from 'zod'
import { Email, Password, Username, Phone, Iban } from '@validex/core'

const schema = z.object({
  email: Email({ blockDisposable: true }),
  password: Password({ length: { min: 8 }, uppercase: { min: 1 } }),
  username: Username({ blockReserved: true }),
  phone: Phone(),
  iban: Iban()
})

Every field has structured error codes you can use for per-rule UI feedback or i18n without string parsing. There are 25 rules total covering these and more.

pnpm add @validex/core zod

GitHub: github.com/chiptoma/validex
npm: @validex/core

Disclosure: I'm the author. If you've been copy-pasting the same refinements across projects, this is what I built to stop doing that.

How I replaced 200 lines of Zod refinements with 12

Ciprian Toma — Tue, 07 Apr 2026 12:03:39 +0000

Every project I start ends up with the same validation code.

Email with disposable domain blocking. Password with strength rules. Phone number via libphonenumber-js. Username with reserved word checks. All built with .refine() and .superRefine() chains on top of Zod.

Different projects, different defaults, forgotten edge cases. The same bugs are showing up in different codebases because I copied the wrong version of the email regex.

Here's what a typical registration form looked like before:

const schema = z.object({
  email: z
    .string()
    .email()
    .refine(
      async (val) => {
        const domain = val.split('@')[1]
        const list = await loadDisposableDomains()
        return !list.includes(domain)
      },
      'Disposable emails not allowed'
    )
    .refine((val) => !val.includes('+'), 'Plus aliases not allowed'),

  password: z
    .string()
    .min(8)
    .max(128)
    .refine((val) => /[A-Z]/.test(val), 'Needs uppercase')
    .refine((val) => /[a-z]/.test(val), 'Needs lowercase')
    .refine((val) => /\d/.test(val), 'Needs digit')
    .refine((val) => /[^A-Za-z0-9]/.test(val), 'Needs special character')
    .refine(
      (val) => !/(.)\1{3,}/.test(val),
      'Too many consecutive characters'
    )
    .refine(async (val) => {
      const common = await loadCommonPasswords()
      return !common.includes(val.toLowerCase())
    }, 'Too common'),

  username: z
    .string()
    .min(3)
    .max(20)
    .regex(/^[a-zA-Z0-9_]+$/, 'Letters, numbers, underscores only')
    .refine((val) => /^[a-zA-Z0-9]/.test(val), 'Must start with letter or number')
    .refine((val) => /[a-zA-Z0-9]$/.test(val), 'Must end with letter or number')
    .refine(async (val) => {
      const reserved = await loadReservedWords()
      return !reserved.includes(val.toLowerCase())
    }, 'Username is reserved'),

  phone: z.string().refine(async (val) => {
    const { isValidPhoneNumber } = await import('libphonenumber-js')
    return isValidPhoneNumber(val)
  }, 'Invalid phone number'),
})

That's around 40 lines for four fields. Across a codebase with multiple forms, it adds up fast. And every .refine() produces a generic Zod error with no structured metadata. Good luck building i18n on top of that.

After

I built validex to stop rewriting this. It's a layer on top of Zod 4 with 25 typed validation rules.

Same form:

import { z } from 'zod'
import { Email, Password, Username, Phone, validate } from '@validex/core'

const schema = z.object({
  email: Email({ blockDisposable: true, blockPlusAlias: true }),
  password: Password({ length: { min: 8 }, consecutive: { max: 3 }, blockCommon: 'basic' }),
  username: Username({ blockReserved: true }),
  phone: Phone({ format: 'e164' }),
})

const result = await validate(schema, formData)

12 lines. Same validation. Every rule returns a standard Zod schema, so it composes with z.object() like anything else.

What this gives you

Structured errors, not strings. Every error carries a namespace, code, and label. Not just "Invalid email" but { namespace: 'email', code: 'disposableBlocked', label: 'Email', domain: 'tempmail.com' }. 141 error codes across 27 namespaces.

Three-tier config merge. Set defaults once with setup(), override per-call when needed:

import { setup, Email } from '@validex/core'

setup({
  rules: {
    email: { blockDisposable: true },
    password: { length: { min: 10 }, special: { min: 2 } },
  },
})

// Every Email() call now blocks disposable domains by default
const schema = z.object({
  email: Email(),                          // uses setup() defaults
  adminEmail: Email({ blockPlusAlias: true }), // adds on top of defaults
})

Built-in defaults, then setup() globals, then per-call options. Three layers, deepmerged.

Heavy data loads on demand. Disposable email domains (~30 kB), common password lists (100 to 10K entries), phone metadata via libphonenumber-js. None of it hits your initial bundle. It loads async on first use, or you can preload at startup:

await preloadData({ disposable: true, passwords: 'strict', phone: 'mobile' })

After preload, everything works synchronously with .parse().

i18n that works. Every error code maps to validation.messages.{namespace}.{code}. Hook up your t() function and validex calls it for every error message:

setup({
  i18n: {
    enabled: true,
    t: (key, params) => i18next.t(key, params),
  },
})

CLI generates translation files:

npx validex fr de es --output ./locales

Bundle size

13 kB Brotli for all 25 rules. Import just one and you ship around 5.5 kB (shared core included). Heavy datasets load async and are not in your initial bundle.

What you import	Brotli
Email only	5.7 kB
Email + Password	6.0 kB
Full form (Email + Password + PersonName + Phone)	6.9 kB
All 25 rules	13.0 kB

The 25 rules

Email, Password, PasswordConfirmation, PersonName, BusinessName, Phone, Website, Url, Username, Slug, PostalCode, LicenseKey, Uuid, Jwt, DateTime, Token, Text, Country, Currency, Color, CreditCard, Iban, VatNumber, MacAddress, IpAddress.

Each one has typed options, sensible defaults and structured error codes.

Framework adapters

Nuxt:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@validex/nuxt'],
  validex: { rules: { email: { blockDisposable: true } } },
})

// Component - useValidation is auto-imported
const { validate, errors, firstErrors, isValid } = useValidation(schema)

Fastify:

await app.register(validexPlugin, {
  rules: { email: { blockDisposable: true } },
})

app.post('/login', async (request, reply) => {
  const result = await request.validate(schema, { source: 'body' })
  if (!result.success) return reply.status(400).send(result.firstErrors)
  return { ok: true }
})

Try it

pnpm add @validex/core zod

GitHub: github.com/chiptoma/validex
npm: @validex/core
Docs: API Reference | Translation Guide

If you've been copy-pasting the same .refine() chains across projects, this is what I built to stop doing that.

Open to feedback on what rules to add next.