|
| 1 | +<div align="center"> |
| 2 | +<img src="https://raw.githubusercontent.com/brazilian-utils/brand/main/github-hero/github-hero-js.png" width="100%" alt="Brazilian Utils" /> |
| 3 | + |
| 4 | +<p>Utilitários para dados brasileiros: CPF, CNPJ, CEP, boleto, Pix, feriados e mais.</p> |
| 5 | + |
| 6 | +[📖 Documentação](https://brazilian-utils.com.br/pt-br/libs/javascript/) · [🇺🇸 Read in English](https://github.com/brazilian-utils/javascript/blob/main/README.md) |
| 7 | + |
| 8 | +[](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) |
| 9 | +[](https://github.com/brazilian-utils/javascript/blob/main/CONTRIBUTING.md#zero-runtime-dependencies) [](https://www.npmjs.com/package/@brazilian-utils/brazilian-utils) |
| 10 | +[](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) [](https://www.bestpractices.dev/projects/14695) |
| 11 | + |
| 12 | +</div> |
| 13 | + |
| 14 | +# Introdução |
| 15 | + |
| 16 | +Brazilian Utils é uma biblioteca de utilitários, sem dependências, para os problemas do dia a dia de quem desenvolve software para o Brasil: validar, formatar, interpretar e gerar CPF, CNPJ, CEP, boleto, Pix, telefone, feriados e mais. |
| 17 | + |
| 18 | +## Por que Brazilian Utils |
| 19 | + |
| 20 | +- **Zero dependências de runtime.** Nada além da biblioteca entra no seu `node_modules` ou no seu bundle. |
| 21 | +- **Tree-shakeable até a função.** `import { isValidCpf }` custa cerca de 0,5 KB minificado (0,3 KB com gzip). Cada utilitário também é um subpath próprio, então os pesados podem ser carregados sob demanda. |
| 22 | +- **Roda em qualquer lugar.** Node.js `^20.19.0 || >=22.12.0`, Bun, Deno e navegadores modernos, todos testados no CI. |
| 23 | +- **Escrita em TypeScript.** Os tipos vêm no pacote, e todo pull request é comparado com a última versão publicada para que a API pública nunca mude em silêncio. |
| 24 | +- **Validada contra as regras oficiais.** Cada validador cita a especificação, lei ou base de dados que implementa, e a suíte de testes passa por mutation testing, não só por cobertura. |
| 25 | +- **Documentada em inglês e português**, com um `llms.txt` para assistentes de IA. |
| 26 | + |
| 27 | +## Instalação |
| 28 | + |
| 29 | +```bash |
| 30 | +npm install @brazilian-utils/brazilian-utils |
| 31 | +``` |
| 32 | + |
| 33 | +O mesmo pacote funciona com `yarn add`, `pnpm add` e `bun add`. Em uma tag `<script>` ele expõe a global `BrazilianUtils`: |
| 34 | + |
| 35 | +```html |
| 36 | +<script src="https://unpkg.com/@brazilian-utils/brazilian-utils/dist/brazilian-utils.umd.cjs"></script> |
| 37 | +``` |
| 38 | + |
| 39 | +### Runtimes suportados |
| 40 | + |
| 41 | +A faixa suportada é o campo `engines` do `package.json`. Cada linha abaixo roda no [workflow de testes](https://github.com/brazilian-utils/javascript/actions/workflows/tests.yml?query=branch%3Amain) em todo pull request. |
| 42 | + |
| 43 | +| Runtime | Suportado | Testado no CI | |
| 44 | +| ----------- | ------------------------- | ----------------------------- | |
| 45 | +| Node.js | `^20.19.0 \|\| >=22.12.0` | 20, 22, 24, 26 | |
| 46 | +| Bun | mais recente | mais recente | |
| 47 | +| Deno | 2.x | 2.x | |
| 48 | +| Navegadores | modernos | Chrome, Firefox, Edge, Safari | |
| 49 | + |
| 50 | +## Como usar |
| 51 | + |
| 52 | +Importe a função que precisar: |
| 53 | + |
| 54 | +```javascript |
| 55 | +import { isValidCpf } from "@brazilian-utils/brazilian-utils"; |
| 56 | + |
| 57 | +isValidCpf("1232454233345"); // false |
| 58 | +``` |
| 59 | + |
| 60 | +A [referência de utilitários](https://brazilian-utils.com.br/pt-br/libs/javascript/) lista todas as funções, agrupadas por família, com opções e exemplos. Os [guias](https://brazilian-utils.com.br/pt-br/guides/) mostram um campo de CPF, um formulário de endereço e mais em React, Angular, Vue e JavaScript puro, e o [guia de migração](https://brazilian-utils.com.br/pt-br/guides/javascript/migration-v1-to-v2/) explica como sair da v1. |
| 61 | + |
| 62 | +- Usa um assistente de código com IA? A documentação está indexada no Context7 como [`/brazilian-utils/javascript`](https://context7.com/brazilian-utils/javascript), e o [llms.txt](https://brazilian-utils.com.br/llms.txt) lista todos os utilitários para outras ferramentas. Veja [Assistentes de IA](https://github.com/brazilian-utils/javascript/blob/main/docs/pt-br/getting-started.md#assistentes-de-ia). |
| 63 | +- O pacote é tree-shakeable. Cada utilitário também está disponível como um subpath próprio (por exemplo, `@brazilian-utils/brazilian-utils/get-cities`), então dá para carregar sob demanda os poucos que são pesados. Veja [Tamanho do bundle](https://github.com/brazilian-utils/javascript/blob/main/docs/pt-br/getting-started.md#tamanho-do-bundle). |
| 64 | + |
| 65 | +## Desenvolvimento |
| 66 | + |
| 67 | +Este repositório usa o Vite+ como ferramenta local. Ele é instalado como dependência, então não é preciso instalar nada globalmente além do Node.js 24 (a versão do `.nvmrc`, que a ferramenta exige; a biblioteca em si suporta Node.js `^20.19.0 || >=22.12.0`). |
| 68 | + |
| 69 | +```bash |
| 70 | +npm install |
| 71 | +npm run check |
| 72 | +npm test |
| 73 | +npm run build |
| 74 | +``` |
| 75 | + |
| 76 | +O [CONTRIBUTING.md](https://github.com/brazilian-utils/javascript/blob/main/CONTRIBUTING.md) lista todos os scripts e as verificações pelas quais um pull request passa. |
| 77 | + |
| 78 | +As notas de cada versão são publicadas nas [GitHub Releases](https://github.com/brazilian-utils/javascript/releases). |
| 79 | + |
| 80 | +## Contribuidores |
| 81 | + |
| 82 | +Nosso "obrigado" vai para [todas as pessoas que contribuíram](https://github.com/brazilian-utils/javascript/blob/main/README.md#contributors). Este projeto segue a especificação [all-contributors](https://github.com/kentcdodds/all-contributors), e contribuições de qualquer tipo são bem-vindas! |
| 83 | + |
| 84 | +## Licença |
| 85 | + |
| 86 | +[MIT](https://github.com/brazilian-utils/javascript/blob/main/LICENSE) |
0 commit comments