Utilities for Brazilian data: CPF, CNPJ, CEP, boleto, Pix, holidays and more.
📖 Documentation · 🇧🇷 Leia em português
Brazilian Utils is a zero-dependency library of small utilities for the day-to-day problems of building software for Brazil: validating, formatting, parsing and generating CPF, CNPJ, CEP, boleto, Pix, phone numbers, holidays and more.
- Zero runtime dependencies. Nothing else lands in your
node_modulesor in your bundle. - Tree-shakeable, down to the function.
import { isValidCpf }costs about 0.5 KB minified (0.3 KB gzipped). Every util is also its own subpath entry, so the heavy ones can be lazy-loaded. - Runs everywhere. Node.js
^20.19.0 || >=22.12.0, Bun, Deno and evergreen browsers, all tested in CI. - Written in TypeScript. Types ship with the package, and every pull request is checked against the last release so the public API never changes silently.
- Validated against the official rules. Every validator cites the specification, law or dataset it implements, and the test suite is mutation-tested, not just covered.
- Documented in English and Portuguese, with an
llms.txtfor AI assistants.
npm install @brazilian-utils/brazilian-utilsThe same package works with yarn add, pnpm add and bun add. In a plain <script> tag it exposes the global BrazilianUtils:
<script src="https://unpkg.com/@brazilian-utils/brazilian-utils/dist/brazilian-utils.umd.cjs"></script>The supported range is the engines field in package.json; every row below runs in the Tests workflow on every pull request.
| Runtime | Supported | Tested in CI |
|---|---|---|
| Node.js | ^20.19.0 || >=22.12.0 |
20, 22, 24, 26 |
| Bun | latest | latest |
| Deno | 2.x | 2.x |
| Browsers | evergreen | Chrome, Firefox, Edge, Safari |
Import the function you need:
import { isValidCpf } from "@brazilian-utils/brazilian-utils";
isValidCpf("1232454233345"); // falseThe utilities reference lists every function, grouped by family, with its options and examples. The guides show a CPF field, an address form and more in React, Angular, Vue and plain JavaScript, and the migration guide covers the move from v1.
- Using an AI coding assistant? The docs are indexed on Context7 as
/brazilian-utils/javascript, and llms.txt lists every util for other tools. See AI assistants. - The package is tree-shakeable. Every util is also available as its own subpath (e.g.
@brazilian-utils/brazilian-utils/get-cities) so you can lazy-load the few heavy ones. See Bundle size.
This repository uses Vite+ as the local toolchain; it is installed as a dependency, so nothing has
to be installed globally beyond Node.js 24 (the version in .nvmrc, which the toolchain needs; the
library itself supports Node.js ^20.19.0 || >=22.12.0).
npm install
npm run check
npm test
npm run buildCONTRIBUTING.md lists every script and the checks a pull request goes through.
Release notes are published through GitHub Releases.
Our "thank you" goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind are welcome!