Utils library for Brazilian-specific businesses.

📖 Documentation

Table of Contents

• Getting Started
  • Why Brazilian Utils
  • Installation
    • Runtime support
  • Usage
  • Development
  • Contributors
  • License

Getting Started

Brazilian Utils is a library focused on solving problems that we face daily in the development of applications for the Brazilian business.

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 1.4 KB minified (0.8 KB gzipped); every util is also its own subpath entry (@brazilian-utils/brazilian-utils/get-cities) for the heavy ones.
• Runs everywhere. Node.js ^20.19.0 || >=22.12.0, Bun, Deno and evergreen browsers, tested in CI on every one of them.
• Written in TypeScript. Types ship with the package; the public API is tracked by an API report so nothing changes silently.
• Validated against the official rules. Every validator cites the specification, law or dataset it implements (@see in the docs), and the test suite is mutation-tested, not just covered.
• Documented in English and Portuguese, with an llms.txt for AI assistants.

Installation

You can install Brazilian Utils in a few ways:

as npm package:

npm install --save @brazilian-utils/brazilian-utils

with yarn package manager:

yarn add @brazilian-utils/brazilian-utils

with pnpm:

pnpm add @brazilian-utils/brazilian-utils

with bun:

bun add @brazilian-utils/brazilian-utils

or <script> tag (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 is exercised by the Tests workflow on every pull request.

Runtime	Supported	Covered 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

To use a utility, import the required function, as shown below:

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

isValidCpf("1232454233345"); // false

You can check a list of utilities by clicking here.

• 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):

Hyan Mandian 💻 📖 🤔 ⚠️	Lucas Veloso 💻 📖 🤔 ⚠️	Andreo Vieira 💻 📖 🤔 🔧	Matheus Almeida 💻 📖 ⚠️	Fernando Rogelin 💻 📖 ⚠️	rodineijf 💻 📖 ⚠️	Emerson Laurentino 💻 📖 ⚠️
Leonardo Dutra 💻 📖 ⚠️	Victor Magalhães 💻 🔧	Amauri Dias 💻 🔧	Felipe F. Diogo 💻 ⚠️	Alan Raso 💻 ⚠️	Felipe Fetter 📖	Rafael Franco 💻 📖
Rafael Pezzetti 💻 ⚠️ 📖	Antonio Roberto Furlaneto 💻 📖 ⚠️	Felipe Nolleto Nascimento 💻 📖 ⚠️	Saulo Joab 📖	Pedro Arantes 💻 📖 ⚠️	Silvio Clécio 💻 📖 ⚠️	Lucas Nascimento 💻
Lincon Kusunoki 💻 📖 ⚠️	Marcelo Cristiano 💻 📖 ⚠️	Tarcísio Batista de Freitas Junior 📖	Lucas Carrias 📖 ⚠️ 💻 🔧	Matheus Andre 📖	Henrique Volponi 💻	Lindsay Ferreira 💻
Vicente Vendramin 💻	Joao Assad 💻 ⚠️	Jander Silva 💻

This project follows the all-contributors specification. Contributions of any kind are welcome!

License

MIT