Utils library for Brazilian-specific businesses.
[π Documentation](https://brazilian-utils.com.br/#/getting-started)
[](https://www.npmjs.com/package/@brazilian-utils/brazilian-utils) [](https://www.npmjs.com/package/@brazilian-utils/brazilian-utils) [](https://github.com/brazilian-utils/javascript/blob/main/LICENSE)
[](https://github.com/brazilian-utils/javascript/blob/main/CONTRIBUTING.md#zero-runtime-dependencies) [](https://brazilian-utils.com.br/#/getting-started?id=bundle-size) [](https://www.npmjs.com/package/@brazilian-utils/brazilian-utils)
[](https://github.com/brazilian-utils/javascript/actions/workflows/build.yml?query=branch%3Amain) [](https://github.com/brazilian-utils/javascript/actions/workflows/tests.yml?query=branch%3Amain) [](https://codecov.io/gh/brazilian-utils/javascript) [](https://github.com/brazilian-utils/javascript/actions/workflows/mutation.yml?query=branch%3Amain) [](https://scorecard.dev/viewer/?uri=github.com/brazilian-utils/javascript)
**Table of Contents**
- [Getting Started](#getting-started)
- [Why Brazilian Utils](#why-brazilian-utils)
- [Installation](#installation)
- [Runtime support](#runtime-support)
- [Usage](#usage)
- [Development](#development)
- [Contributors](#contributors)
- [License](#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:
```bash
npm install --save @brazilian-utils/brazilian-utils
```
with yarn package manager:
```bash
yarn add @brazilian-utils/brazilian-utils
```
with pnpm:
```bash
pnpm add @brazilian-utils/brazilian-utils
```
with bun:
```bash
bun add @brazilian-utils/brazilian-utils
```
or `
```
### Runtime support
The supported range is the `engines` field in `package.json`; every row below is exercised by the [Tests workflow](https://github.com/brazilian-utils/javascript/actions/workflows/tests.yml?query=branch%3Amain) 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:
```javascript
import { isValidCpf } from "@brazilian-utils/brazilian-utils";
isValidCpf("1232454233345"); // false
```
You can check a list of utilities [by clicking here](https://brazilian-utils.com.br/#/utilities).
- 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](https://brazilian-utils.com.br/#/getting-started?id=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`).
```bash
npm install
npm run check
npm test
npm run build
```
[CONTRIBUTING.md](CONTRIBUTING.md) lists every script and the checks a pull request goes through.
Release notes are published through [GitHub Releases](https://github.com/brazilian-utils/javascript/releases).
## Contributors
Our "thank you" goes to these wonderful people ([emoji key](https://github.com/kentcdodds/all-contributors#emoji-key)):
