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_modules or 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.txt for 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. 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.
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!
License
MIT