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.

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