Skip to content

docs: move the v1 to v2 migration guide into the guides #626

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hyanmandian merged 2 commits into from
Oct 9, 2026
Merged

docs: move the v1 to v2 migration guide into the guides #626

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3a626cb
docs: move the v1 to v2 migration guide into the guides
hyanmandian Oct 9, 2026
9bc5981
Merge branch 'main' into hyan/migration-guide
hyanmandian Oct 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/_sidebar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@
* [Address from a CEP](guides/address-form.md)
* [State and city](guides/state-city.md)
* [Schema libraries](guides/schema.md)
* [Migration v1 to v2](migration-v1-to-v2.md)
* [Migration v1 to v2](guides/migration-v1-to-v2.md)
5 changes: 3 additions & 2 deletions docs/migration-v1-to-v2.md → docs/guides/migration-v1-to-v2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
title: "Migration Guide: v1 to v2"
description: "How to move a project from Brazilian Utils v1.x to v2: the renamed exports, the deprecated aliases that still work and a checklist to follow."
keywords: ["migration", "v1", "v2", "deprecated", "renamed exports", "upgrade"]
order: 1
---

This guide covers moving a project from Brazilian Utils v1.x to v2.
Expand All @@ -22,12 +23,12 @@ Four v1 helpers were internal and have no alias. Replace them before upgrading:
## What changed

- **Names are camelCase.** See [Renamed functions](#renamed-functions).
- **Tree-shaking works down to the function**, and every util is also its own subpath (`@brazilian-utils/brazilian-utils/is-valid-cpf`), so the heavy ones can be lazy-loaded. See [Bundle size](getting-started.md#bundle-size).
- **Tree-shaking works down to the function**, and every util is also its own subpath (`@brazilian-utils/brazilian-utils/is-valid-cpf`), so the heavy ones can be lazy-loaded. See [Bundle size](../getting-started.md#bundle-size).
- **Alphanumeric CNPJ.** `isValidCnpj` and `generateCnpj` accept the new alphanumeric format with `{ version: 2 }`. Numeric (version 1) stays the default. See [`generateCnpj` and the version](#generatecnpj-and-the-version).
- **`getAddressInfoByCep`** accepts a `providers` option, pads a numeric CEP, and throws typed errors: `GetAddressInfoByCepValidationError`, `GetAddressInfoByCepNotFoundError` and `GetAddressInfoByCepServiceError`. Calls without options work as in v1.
- **`getCities`** returns the list sorted alphabetically. Since 2.4.0 it is deprecated: `getMunicipalities('SP')` returns the same municipalities with their IBGE codes, and `getMunicipalityByCode('3550308')` looks one up offline.
- **`isValidIe`** takes one object since 2.4.0, `isValidIe({ value, stateCode })`. The positional form is deprecated.
- **Many new utilities** since v2: holidays and business days, Pix, NF-e keys, boleto parsing, phone formatting, bank accounts and lookups, classification codes (CBO, CNAE, NCM, CFOP), municipalities offline, numbers in words and more. They are all in the [utilities reference](utilities.md).
- **Many new utilities** since v2: holidays and business days, Pix, NF-e keys, boleto parsing, phone formatting, bank accounts and lookups, classification codes (CBO, CNAE, NCM, CFOP), municipalities offline, numbers in words and more. They are all in the [utilities reference](../utilities.md).
- **Tooling** moved to Vite+ and Vitest, with browser tests in CI. This only matters if you contribute; see [CONTRIBUTING.md](https://github.com/brazilian-utils/javascript/blob/main/CONTRIBUTING.md).

## Renamed functions
Expand Down
2 changes: 1 addition & 1 deletion docs/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@
<p>
This site renders its Markdown in the browser and needs JavaScript. The same pages are available as
plain Markdown: <a href="/getting-started.md">getting started</a>, <a href="/utilities.md">utilities</a>,
<a href="/migration-v1-to-v2.md">migration from v1 to v2</a> and the
<a href="/guides/migration-v1-to-v2.md">migration from v1 to v2</a> and the
<a href="/pt-br/getting-started.md">Portuguese version</a>, or in one file at <a href="/llms-full.txt">llms-full.txt</a>.
</p>
</noscript>
Expand Down
2 changes: 1 addition & 1 deletion docs/pt-br/_sidebar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@
* [Endereço pelo CEP](pt-br/guides/address-form.md)
* [Estado e cidade](pt-br/guides/state-city.md)
* [Bibliotecas de schema](pt-br/guides/schema.md)
* [Migração v1 para v2](pt-br/migration-v1-to-v2.md)
* [Migração v1 para v2](pt-br/guides/migration-v1-to-v2.md)
1 change: 1 addition & 0 deletions docs/pt-br/migration-v1-to-v2.md → docs/pt-br/guides/migration-v1-to-v2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
title: "Guia de migração: v1 para v2"
description: "Como migrar um projeto do Brazilian Utils v1.x para a v2: os exports renomeados, os aliases descontinuados que ainda funcionam e um checklist para seguir."
keywords: ["migração", "v1", "v2", "descontinuado", "exports renomeados", "atualização"]
order: 1
---

Este guia mostra como migrar um projeto do Brazilian Utils v1.x para a v2.
Expand Down
Loading