@br-validators/core

@br-validators/core

The Brazilian document validation library for TypeScript.
Validate, format, and generate CPF, CNPJ (including the new alphanumeric format), NF-e, BR Code PIX, boleto, IE (all 27 states), and 15+ more — zero dependencies, fully typed, never throws.

npm install @br-validators/core

Try it now → doc-raiz-playground.vercel.app
CLI → npm install -g @br-validators/cli

⚠️ The unscoped br-validators on npm is a different package. Use @br-validators/core.

Why this library

Every Brazilian SaaS eventually reinvents CPF validation — usually wrong.
@br-validators/core implements each algorithm from its official primary source (Receita Federal, Bacen, CONTRAN, TSE, SEFAZ, FEBRABAN, Anatel) so you don't have to.

• ✅ CNPJ alfanumérico — new RFB format (effective July 2026), ready now
• ✅ 18+ document types — CPF, CNPJ, CEP, NF-e chave, BR Code PIX, boleto (cobrança + arrecadação), CNH, RENAVAM, placa, PIS/PASEP, PIX key, cartão de crédito, IE (27 UFs), IE produtor rural, título de eleitor, telefone, + platform APIs above
• ✅ Zero runtime dependencies — pure TypeScript logic, no HTTP calls
• ✅ Never throws — every function returns { ok: true, value } | { ok: false, message, code }
• ✅ Tree-shakeable — subpath imports per document type
• ✅ ESM only, Node ≥ 18, works in browser, Bun, Deno

Quick start

import { validateCpf, formatCpf } from '@br-validators/core';

validateCpf('123.456.789-09');
// { ok: true, value: '12345678909' }

formatCpf('12345678909');
// { ok: true, formatted: '123.456.789-09' }

validateCpf('111.111.111-11');
// { ok: false, message: 'CPF with all identical digits is invalid', code: 'KNOWN_INVALID_PATTERN' }

CNPJ — numeric and alphanumeric (new RFB format)

import { validateCnpj, formatCnpj } from '@br-validators/core/cnpj';

// Numeric (current format)
validateCnpj('11.222.333/0001-81');
// { ok: true, value: '11222333000181', format: 'numeric' }

// Alphanumeric (new format — effective July 2026)
validateCnpj('12ABC34501DE35');
// { ok: true, value: '12ABC34501DE35', format: 'alphanumeric' }

formatCnpj('12ABC34501DE35');
// { ok: true, formatted: '12.ABC.345/01DE-35' }

Auto-detect document type

import { detect } from '@br-validators/core';

detect('123.456.789-09');
// { type: 'cpf', ok: true, value: '12345678909' }

detect('ABC1D23');
// { type: 'placa', ok: true, format: 'mercosul' }

detect('110042490114', { uf: 'SP' });
// { type: 'inscricao-estadual', ok: true }

Generate valid documents for tests

import { generate } from '@br-validators/core';

generate('cpf', { seed: 42 });           // reproducible, always valid
generate('cnpj', { format: 'alphanumeric', masked: true });
generate('placa', { format: 'mercosul' });
generate('renavam');
generate('cnh');
generate('inscricao-estadual', { uf: 'SP', seed: 42 });
generate('titulo-eleitor', { uf: 'SC', seed: 42 });
generate('cartao-credito', { brand: 'visa', seed: 42 });
generate('pix', { seed: 42 });           // EVP UUID — Bacen DICT
generate('nfe-chave', { seed: 42 });     // MOC §2.2.6 modulo-11 DV
generate('brcode', { seed: 42 });        // static PIX EMV + CRC16
generate('boleto', { masked: true });    // FEBRABAN cobrança Situação 1
generate('boleto-arrecadacao');          // FEBRABAN Layout v7
generate('inscricao-estadual-produtor-rural', { masked: true }); // SP SINTEGRA Bloco II

generate() is for test fixtures and seed data only — never use in production.
Alphanumeric CPF: generate('cpf', { format: 'alphanumeric' }) throws CPF_ALPHA_SPEC_PENDING until RFB publishes the official algorithm (OFFICIAL-SOURCES.md).

ETL / data cleanup

import { sanitize } from '@br-validators/core';

sanitize(' 123.456.789-09 ', 'cpf');
// { ok: true, value: '12345678909', fixes: ['trimmed', 'removed_non_digits'] }

sanitize('110.042.490.114', 'inscricao-estadual', { uf: 'SP' });
// { ok: true, value: '110042490114', fixes: [...] }

NF-e chave de acesso (44 digits)

import { validateNfeChave, parseNfeChave } from '@br-validators/core/nfe-chave';

const result = validateNfeChave('52060433009911002506550120000007800267301615');
// { ok: true, parsed: { cUF: '52', cnpj: '33009911002506', mod: '55', ... }, uf: 'GO' }

BR Code (PIX QR payload)

import {
  buildStaticPixBrCode,
  parseBrCode,
  validateBrCode,
} from '@br-validators/core/brcode';

// Permanent static QR (no amount — payer sets value at payment time)
const payload = buildStaticPixBrCode({
  pixKey: '[e-mail]',
  merchantName: 'Fulano de Tal',
  merchantCity: 'BRASILIA',
});
validateBrCode(payload).ok; // true

// Fixed-value static QR
buildStaticPixBrCode({
  pixKey: '[e-mail]',
  merchantName: 'Fulano de Tal',
  merchantCity: 'BRASILIA',
  amount: '10.50',
});

parseBrCode(payload);
// { ok: true, pixKey, pixKeyType, merchantName, merchantCity, amount, txid }

Playground: doc-raiz-playground.vercel.app/pix renders the QR image from buildStaticPixBrCode output. Official sources: Bacen Manual BR Code · Manual de Padrões PIX.

Boleto — cobrança + arrecadação

import { validateBoleto, validateArrecadacao } from '@br-validators/core/boleto';

validateBoleto('03399.02579 08991.834006 71742.301014 6 14500000099668');
// cobrança Situação 1/2 — FEBRABAN FB-0061/2021

validateArrecadacao('846300000003812345678906123456789015234567890129');
// arrecadação 48-digit — FEBRABAN Layout v7

Platform APIs — mask, compare, batch, diff

import { mask, compare, batch, diff } from '@br-validators/core';

mask('12345678909', 'cpf');
// { ok: true, formatted: '123.456.789-09' }

compare('123.456.789-09', '12345678909', 'cpf');
// { equal: true }

batch(['12345678909', 'invalid'], 'cpf');
// { valid: [...], invalid: [...], summary: { total: 2, valid: 1, invalid: 1 } }

diff('12345678909', '12345678901', 'cpf');
// { changed: true, fields: [{ field: 'dv', a: '09', b: '01' }] }

Per-type rules and official sources: docs/OFFICIAL-SOURCES.md · API contract: docs/LIBRARY-API.md

Form handler (React / Next.js)

'use client';
import { validateCnpj, formatCnpj } from '@br-validators/core/cnpj';
import { useState } from 'react';

export function CnpjField() {
  const [input, setInput] = useState('');
  const result = input ? validateCnpj(input) : null;
  const formatted = result?.ok ? formatCnpj(result.value) : null;

  return (
    <div>
      <input value={input} onChange={e => setInput(e.target.value)} />
      {formatted?.ok && <p>✅ {formatted.formatted}</p>}
      {result && !result.ok && <p>❌ {result.message}</p>}
    </div>
  );
}

Shell / CI

br-validators cnpj validate "$CNPJ" --quiet || exit 1
br-validators ie validate "$IE" --uf SP --json
br-validators detect '123.456.789-09' --json
br-validators generate cpf --seed 42 --masked
br-validators generate pix --seed 42
br-validators generate nfe-chave --seed 42
br-validators generate brcode --seed 42
br-validators generate boleto --masked --seed 42
br-validators generate boleto-arrecadacao --seed 42
br-validators generate inscricao-estadual-produtor-rural --masked --seed 42

All supported types

Document	Subpath import	CLI	Playground
CPF	@br-validators/core/cpf	br-validators cpf …	/cpf
CNPJ (numeric + alphanumeric)	@br-validators/core/cnpj	br-validators cnpj …	/cnpj
CEP	@br-validators/core/cep	br-validators cep …	/cep
Telefone	@br-validators/core/telefone	br-validators telefone …	/telefone
CNH	@br-validators/core/cnh	br-validators cnh …	/cnh
RENAVAM	@br-validators/core/renavam	br-validators renavam …	/renavam
Título de Eleitor	@br-validators/core/titulo-eleitor	br-validators titulo-eleitor …	/titulo-eleitor
Placa (Mercosul + legada)	@br-validators/core/placa	br-validators placa …	/placa
PIS / PASEP / NIS	@br-validators/core/pis-pasep	br-validators pis-pasep …	/pis
PIX key	@br-validators/core/pix	br-validators pix …	/pix
BR Code (PIX QR payload + builder)	@br-validators/core/brcode	br-validators brcode …	/brcode
Boleto cobrança (Situação 1 + 2)	@br-validators/core/boleto	br-validators boleto …	/boleto
Boleto arrecadação (48/44)	@br-validators/core/boleto	br-validators boleto …	/boleto
NF-e / NFC-e chave (44 digits)	@br-validators/core/nfe-chave	br-validators nfe-chave …	/nfe-chave
Cartão de crédito (Luhn)	@br-validators/core/cartao-credito	br-validators cartao …	/cartao-credito
Inscrição Estadual (27 UFs)	@br-validators/core/inscricao-estadual	br-validators ie … --uf SP	/ie
IE Produtor Rural	@br-validators/core/inscricao-estadual-produtor-rural	br-validators ie … (auto P)	/ie
detect()	@br-validators/core/detect	br-validators detect …	/detect
sanitize()	@br-validators/core/sanitize	br-validators sanitize …	/sanitize
mask()	@br-validators/core/mask	—	via per-type format
compare()	@br-validators/core/compare	—	—
batch()	@br-validators/core/batch	—	—
diff()	@br-validators/core/diff	—	—
generate()	@br-validators/core/generate	br-validators generate …	/generate
buildStaticPixBrCode()	@br-validators/core/brcode	—	/pix (QR panel)

Full official sources per type: docs/OFFICIAL-SOURCES.md

Tree-shaking

// Only ships the CPF module — nothing else
import { validateCpf } from '@br-validators/core/cpf';

// Only ships NF-e module
import { parseNfeChave } from '@br-validators/core/nfe-chave';

Related packages

Package	Status
@br-validators/cli	Published
@br-validators/zod	Published — Zod 3/4 schemas
@br-validators/react-hook-form	Published — RHF resolvers

Contributing

Issues, corrections, and new document types are welcome.
See CONTRIBUTING.md and open good first issue items.

License

MIT — permanently free and open source.