gem-hunter
Language: TypeScript
Ship production-ready schemas with Zod Toolkit
Stop rewriting validators. Ship production-ready schemas with Zod Toolkit. 🚀
Built to enhance Zod standard validations, zod-toolkit integrates seamlessly into your projects the same way you’d use Zod.
npm install zod-toolkit
yarn add zod-toolkit
pnpm add zod-toolkit
| Schema | Usage | Description |
|---|---|---|
fullname |
z.fullname() |
Validates full names (first and last name required, no numbers) |
username |
z.username() |
Validates usernames (3–20 chars, alphanumeric with . and _) |
otp |
z.otp(length?) |
Validates one-time passwords with a given digit length (default: 6) |
nodeEnv |
z.nodeEnv() |
Validates Node.js environment (production, development, test, staging) |
port |
z.port() |
Validates port numbers as string (0–65535) |
logLevel |
z.logLevel() |
Validates log levels (trace, debug, info, warn, error, fatal) |
hostname |
z.hostname() |
Validates hostnames and IPv4/IPv6 addresses (extends Zod's z.hostname()) |
databaseUrl |
z.databaseUrl() |
Validates database URLs (postgres, mysql, mongodb, redis) |
duration |
z.duration() |
Validates durations like 10s or 5m and transforms them into milliseconds |
csv |
z.csv(item?) |
Splits a comma-separated string into an array, validating each item |
password |
z.password() |
Validates passwords (8+ chars, lower/upper case, number and symbol) |
slug |
z.slug() |
Validates kebab-case slugs |
hexColor |
z.hexColor() |
Validates hex colors (#RGB, #RGBA, #RRGGBB, #RRGGBBAA) |
semver |
z.semver() |
Validates SemVer 2.0.0 versions |
Note
z.hostname() and z.coerce.boolean() replace the Zod schemas with the same name.
z.hostname() keeps accepting domain names (localhost, example.com, example.com.) and IPv4, and additionally accepts IPv6 (::1) and bracketed IPv6 ([::1]). It rejects dotted numbers such as 256.1.1.1 or 1.2.3, which Zod's z.hostname() accepts: per RFC 3696 the last label of a hostname cannot be all digits, and such a string is read as an IPv4 address, not a name.z.coerce.boolean() accepts true/false, 1/0, yes/no and on/off (case-insensitive) and rejects anything else, so "false" becomes false instead of true.| Schema | Usage | Description |
|---|---|---|
port |
z.coerce.port() |
Validates and coerces port numbers as number (0–65535) |
boolean |
z.coerce.boolean() |
Coerces env-style booleans (true/false, 1/0, yes/no, on/off) |
| Schema | Usage | Description |
|---|---|---|
cpf |
z.br.cpf() |
Validates CPF numbers (000.000.000-00 or 00000000000) |
cnpj |
z.br.cnpj() |
Validates numeric and alphanumeric CNPJs (AA.AAA.AAA/AAAA-00 or AAAAAAAAAAAA00, uppercase) |
cep |
z.br.cep() |
Validates CEP postal codes (00000-000 or 00000000) |
You just need to define a schema and use custom validations. For the purposes of this guide, we'll use a simple object schema:
import { z } from "zod-toolkit"; const Customer = z.object({ username: z.username(), oneTimePassword: z.otp(6), cpf: z.br.cpf(), cnpj: z.br.cnpj(), }); type CustomerSchema = z.infer<typeof Customer>;
Zod Toolkit has built-in locale support. All custom schemas return localized error messages that switch dynamically at parse time — no need to recreate your schemas after changing the locale.
import { z } from "zod-toolkit"; // Default locale is "en" z.locale.set("pt");
When you call z.locale.set(), it also configures Zod's built-in error messages (via z.config()), so both Zod Toolkit schemas and native Zod schemas use the same language.
z.locale.current; // "pt"
Error messages are resolved at parse time, so you can change the locale at any point and all schemas will reflect the new language:
import { z } from "zod-toolkit"; const schema = z.br.cpf(); // Default (English) z.treeifyError(schema.safeParse("invalid").error).errors; // ["Invalid CPF: must be 11 digits in the format 000.000.000-00 or 00000000000."] // Switch to Portuguese z.locale.set("pt"); z.treeifyError(schema.safeParse("invalid").error).errors; // ["CPF inválido: deve conter 11 dígitos no formato 000.000.000-00 ou 00000000000."]
You can always override the default message by passing a custom error parameter. This takes priority over the locale:
z.br.cpf({ error: "Please enter a valid CPF" }); z.otp(6, { error: "Invalid code" }); z.username({ error: "Choose a valid username" });
Composite validators run as an ordered, fail-fast sequence of named steps, each with its own localized message:
| Validator | Steps (in order) |
|---|---|
br.cnpj, br.cpf |
format → repeated → checkDigit |
br.cep |
format → repeated → range |
username |
length → charset |
port, coerce.port |
format → range |
Override individual steps with errors. Precedence: errors[step] > error > localized default.
z.br.cnpj({ errors: { checkDigit: "Check the last two digits" } }); z.br.cpf({ error: (issue) => `Failed at: ${issue.params?.step}` });
Unknown step names are a compile-time error.
Zod Toolkit locale support is powered by Zod v4's locale system. The following locales are available:
| Code | Language | Code | Language | Code | Language |
|---|---|---|---|---|---|
ar |
Arabic | he |
Hebrew | no |
Norwegian |
az |
Azerbaijani | hu |
Hungarian | ota |
Ottoman Turkish |
be |
Belarusian | id |
Indonesian | pl |
Polish |
bg |
Bulgarian | is |
Icelandic | ps |
Pashto |
ca |
Catalan | it |
Italian | pt |
Portuguese |
cs |
Czech | ja |
Japanese | ru |
Russian |
da |
Danish | ka |
Georgian | sl |
Slovenian |
de |
German | kh |
Khmer | sv |
Swedish |
en |
English | km |
Khmer | ta |
Tamil |
eo |
Esperanto | ko |
Korean | th |
Thai |
es |
Spanish | lt |
Lithuanian | tr |
Turkish |
fa |
Persian | mk |
Macedonian | ua |
Ukrainian |
fi |
Finnish | ms |
Malay | uk |
Ukrainian |
fr |
French | nl |
Dutch | ur |
Urdu |
frCA |
French (Canada) | vi |
Vietnamese | ||
yo |
Yoruba | ||||
zhCN |
Chinese (Simplified) | ||||
zhTW |
Chinese (Traditional) |
Note
Zod Toolkit currently ships custom error messages in en and pt. For other locales, Zod's built-in messages will be localized, but Zod Toolkit's custom schema messages will fall back to English. Contributions for additional translations are welcome!