Skip to main content

Getting started

🚀 Full support for the new alphanumeric CNPJ format.

A JavaScript/TypeScript toolkit to handle the main operations with Brazilian-related data: CPF (Individual's Taxpayer ID) and CNPJ (Business Tax ID). It exposes a unified API that wraps cpf-utils and cnpj-utils in a single entry point.

Platform Support​

Node.jsBunDenoChromeEdgeFirefoxSafariOperaIE
v16+ ✔v1.0+ ✔⚠️ untestedLatest ✔Latest ✔Latest ✔Latest ✔Latest ✔11 ✔

Features​

  • ✅ Unified API: One default instance with cpf and cnpj sub-modules; each sub-module offers format, generate, and isValid
  • ✅ Single entry point: Install one package for both CPF (demo) and CNPJ (demo) operations
  • ✅ Reusable instance: BrUtils class with optional default settings for the CPF and CNPJ utils (options or instances)
  • ✅ Full re-exports: All classes, options, errors, and types from cpf-utils and cnpj-utils
  • ✅ TypeScript support: Full type definitions and strict-mode compatible
  • ✅ Error handling: Same errors and exceptions as the underlying packages

Installation​

# using NPM
$ npm install --save br-utils

# using Bun
$ bun add br-utils

Quick Start​

// ES Modules — default instance
import brUtils from 'br-utils'

// Or named exports (tree-shaking)
import { BrUtils, cpfUtils, cnpjUtils } from 'br-utils'

// Common JS
const brUtils = require('br-utils')

Basic usage:

// CPF (personal ID)
brUtils.cpf.format('47844241055')           // '478.442.410-55'
brUtils.cpf.generate({ format: true })      // e.g. '478.442.410-55'
brUtils.cpf.isValid('123.456.789-09')      // true

// CNPJ (employer ID)
brUtils.cnpj.format('03603568000195')      // '03.603.568/0001-95'
brUtils.cnpj.generate({ format: true })   // e.g. '03.603.568/0001-95'
brUtils.cnpj.isValid('98765432000198')    // true

For legacy frontends, include the UMD build (e.g. minified) in a <script> tag; brUtils is exposed globally:

<script src="https://cdn.jsdelivr.net/npm/br-utils@latest/dist/br-utils.min.js"></script>

Usage​

brUtils (default instance)​

The default export is a pre-built BrUtils instance. Use it for quick one-off calls:

  • cpf: Access the CPF utilities (CpfUtils). Use brUtils.cpf.format(), brUtils.cpf.generate(), brUtils.cpf.isValid() and the same options as in cpf-utils.
  • cnpj: Access the CNPJ utilities (CnpjUtils). Use brUtils.cnpj.format(), brUtils.cnpj.generate(), brUtils.cnpj.isValid() and the same options as in cnpj-utils.

BrUtils (class)​

For custom default CPF or CNPJ utils, create your own instance:

import { BrUtils } from 'br-utils'

// Default settings (all optional)
const utils = new BrUtils({
  cpf: {
    formatter: { hidden: true, hiddenKey: '#' },
    generator: { format: true },
  },
  cnpj: {
    formatter: { hidden: true },
    generator: { type: 'numeric', format: true },
  },
})

utils.cpf.format('47844241055')        // '478.###.###-##'
utils.cpf.generate()                  // e.g. '005.265.352-88'
utils.cnpj.format('03603568000195')   // '03.603.***/****-**'
utils.cnpj.generate()                // e.g. '73.008.535/0005-06'

// Access or replace internal instances
utils.cpf   // CpfUtils
utils.cnpj  // CnpjUtils
  • constructor(defaultSettings?): Optional BrUtilsSettingsInput — cpf and cnpj can each be a CpfUtils / CnpjUtils instance or an options object (CpfUtilsSettingsInput / CnpjUtilsSettingsInput). Omitted keys use default instances.
  • cpf: Getter/setter for the CPF utilities instance. Setter accepts CpfUtils, CpfUtilsSettingsInput, or null/undefined to reset to defaults.
  • cnpj: Getter/setter for the CNPJ utilities instance. Setter accepts CnpjUtils, CnpjUtilsSettingsInput, or null/undefined to reset to defaults.

Using the underlying helpers and re-exports​

You can use the re-exported CPF and CNPJ helpers and classes directly:

import {
  cpfFmt,
  cpfGen,
  cpfVal,
  CpfUtils,
  cnpjFmt,
  cnpjGen,
  cnpjVal,
  CnpjUtils,
} from 'br-utils'

cpfFmt('47844241055', { dashKey: '_' })   // '478.442.410_55'
cpfGen({ prefix: '123456' })              // e.g. '12345678901'
cpfVal('123.456.789-09')                  // true

cnpjFmt('03603568000195', { slashKey: '|' })  // '03.603.568|0001-95'
cnpjGen({ type: 'numeric' })                  // e.g. '65453043000178'
cnpjVal('98.765.432/0001-98')                 // true

See cpf-utils and cnpj-utils for full option and error details.

API​

Exports​

  • brUtils (default): Pre-built BrUtils instance with cpf and cnpj; for CommonJS and UMD, the object also carries all re-exports from cpf-utils and cnpj-utils.
  • BrUtils: Class to create an instance with optional default CPF and CNPJ utils settings.
  • BrUtilsSettingsInput, BrUtilsSettingsType: Types for the constructor settings.
  • CPF: All exports from cpf-utils (e.g. cpfUtils, CpfUtils, cpfFmt, cpfGen, cpfVal, formatter/generator/validator classes, options, errors, types).
  • CNPJ: All exports from cnpj-utils (e.g. cnpjUtils, CnpjUtils, cnpjFmt, cnpjGen, cnpjVal, formatter/generator/validator classes, options, errors, types).

Errors & Exceptions​

Errors and exceptions are the same as in cpf-utils and cnpj-utils. The BrUtils constructor and the cpf/cnpj setters can throw the same errors as the underlying package constructors. See each package’s README for the full list.

Contribution & Support​

We welcome contributions! Please see our Contributing Guidelines for details. If you find this project helpful, please consider:

License​

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog​

See CHANGELOG for a list of changes and version history.

Made with ❤️ by Lacus Solutions