Table of Contents
Getting Started
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.
Why Brazilian Utils
- 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.
Installation
npm install @brazilian-utils/brazilian-utils
The 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>
Runtime support
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 |
Usage
Import the function you need:
import { isValidCpf } from "@brazilian-utils/brazilian-utils";
isValidCpf("1232454233345"); // false
The utilities reference lists every function, grouped by family, with its options and examples.
- 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.
Development
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 build
CONTRIBUTING.md lists every script and the checks a pull request goes through.
Release notes are published through GitHub Releases.
Contributors
Our "thank you" goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind are welcome!