Brazilian Utils treats CPF and Pix validation as a subpath import problem

The subpath export is the load-bearing decision

Most utility libraries are a single entry point, and importing one function drags in the package. This one takes the opposite approach and states the cost per function: `import { isValidCpf }` is described as about 0.5 KB minified and 0.3 KB gzipped. Every util is additionally published as its own subpath, so the heavier ones can be lazy-loaded on demand.

The package manifest backs that up. The exports map has a root entry with separate `import` and `require` conditions pointing at an ESM build and a UMD CommonJS build with their own type declarations, plus a wildcard `*` export entry that maps any util name to its own dist file. That wildcard is what makes per function subpath imports work without enumerating every one in the manifest. `sideEffects` is false, which is what lets a bundler drop unused functions, and `type` is `module`.

It also ships to places other than npm. The repository root has a jsr.json for JSR, a context7.json for documentation indexing, and the README points at an llms.txt for AI assistants. The global build is exposed as `BrazilianUtils` when you load the UMD file from a script tag, which is the only path that works without a bundler.

What it covers and what that means for trust

The list of families is broad for a library that describes itself as small utilities: CPF, CNPJ, CEP, boleto, Pix, phone numbers, holidays, and from the package keywords also CBO, CEST, CFOP, CNAE, CNH, state registration, IBAN, IBGE, municipalities, NCM, NF-e, PIS and RENAVAM. Each of those can be validated, formatted, parsed and, for many of them, generated.

The claim that matters for adoption is that every validator cites the specification, law or dataset it implements, and that the test suite is mutation tested rather than only covered. Mutation testing is the honest counterweight to a claim like that, since it measures whether the assertions would catch a broken validator, not just whether a line ran. The repository has a stryker.config.json for that purpose and a codecov badge for coverage.

There is also a CI workflow that checks every pull request against the last published release with api-extractor.json in the root, which is how the claim that the public API never changes silently is enforced rather than asserted.

Installing and the first call

The package is `@brazilian-utils/brazilian-utils` on npm:

npm install @brazilian-utils/brazilian-utils

The same package works with `yarn add`, `pnpm add` and `bun add`. Usage is a named import and a call:

import { isValidCpf } from "@brazilian-utils/brazilian-utils";

isValidCpf("1232454233345"); // false

Runtime support is declared in the `engines` field: Node.js `^20.19.0 || >=22.12.0`, Bun latest, Deno 2.x and evergreen browsers. The CI matrix tests Node 20, 22, 24 and 26, Bun latest, Deno 2.x, and Chrome, Firefox, Edge and Safari.

The version floor is worth reading carefully if you are on Node 20, since 20.19.0 excludes earlier 20.x releases. Local development needs more than the library does: the toolchain is Vite+ installed as a dependency, and the README says Node.js 24, the version in .nvmrc, is required to work on the repository.

The migration from v1 is the adoption cost

This is a v2 library. The README links a dedicated migration guide covering the move from v1, which tells you the API changed rather than merely grew. The release history shows 2.3.0 on 2026-04-09, 2.4.0 on 2026-09-17 and 2.5.0 on 2026-10-03, with the repository not archived and the last push on 2026-10-13.

Given the function-per-subpath design, a major version bump is expensive for users in a specific way. Every import site in your codebase may need rewriting, not just the call, which is the usual cost and also the reason the API diff check in CI matters when you upgrade.

The documentation is split. The utilities reference lists every function grouped by family with options and examples, the guides cover a CPF field and an address form in React, Angular, Vue and plain JavaScript, and there is a separate Portuguese README in the repository. That is a genuine strength for a library whose validation rules are statutory and change without much notice.

Where it is the wrong tool

It validates, formats, parses and generates. It does not resolve. CEP in Brazil is a postal code that maps to an address, and this library does not ship a lookup for what a given CEP means, so an address form still needs a postal service behind it.

Phone number support has the same shape of limitation. Formatting a Brazilian number to national convention is a pure function, but deciding whether a number can actually receive SMS, or which area code is assigned, is carrier data, not check digit arithmetic.

Generation is where teams get into trouble. A generator that produces a structurally valid CPF gives you an identifier that passes `isValidCpf` and will be rejected at the other end. The README does not claim generated identifiers are registered anywhere, and for test fixtures that is exactly what you want, but for a production form it is a trap. Use a generator for fixtures, not for real users.

Finally, everything here is specific to Brazil. Outside the country the library has no meaning, which is fine, but it means the bundled size cannot be reduced by dropping locales, because there are no other locales.

Against writing the check digit yourself

A CPF validator is two check digits computed with a specific modulo eleven rule over the first nine digits. It is copied from blog posts, and most copies get the special case where all digits are identical wrong, because a sequence of identical digits passes a naive check digit test while being invalid.

The case for the library is that the rules are statutory and the library cites them, tests them and mutation tests the tests. The case against it is that you are adding a dependency, a package surface and a migration guide to your build for a function you could own end to end, and that if the rule ever changes you would need to patch the library anyway.

A middle path exists and the manifest supports it. Importing one function through its subpath keeps the cost at a few hundred bytes, so you could adopt it for the identifiers you get wrong most often and keep your own code for the rest.

The repository also shows the governance signals worth weighing: a CODE_OF_CONDUCT.md, a SECURITY.md, a SUPPORT.md, a MAINTAINERS.md, an osv-scanner.toml, an openvex.json and an OpenSSF Scorecard badge. None of that is a guarantee, but it is a different posture from a single maintainer utility.

Editorial conclusion

Adopt Brazilian Utils if your product collects Brazilian tax identifiers, addresses or Pix data and you want check digit validation without writing regex and modulo arithmetic yourself. Do not adopt it for phone parsing or CEP lookup outside Brazil, and do not expect its generators to produce identifiers that pass a government registry check, since generation and validation are separate concerns here. Verify first by running isValidCpf on the identifiers your existing code accepts, because accepting invalid input is the behaviour most likely to differ from what you have now, and check that your bundler honours the sideEffects false field if you rely on tree shaking.

Frequently asked questions

Official sources

1. brazilian-utils/javascript on GitHub
2. License: MIT
3. Project website
4. README
5. Releases