Configurando Custom Path Mapping no Node.js

Neste artigo, exploraremos em detalhes o que é path mapping, como ele funciona e quais são seus benefícios para o desenvolvimento em aplicações Node.js.

*Texto de Jakson Xavier, Software Developer @ Rocketseat

O que é path mapping?

Na tradução literal entendemos como "mapeamento de caminhos”. É uma técnica usada para simplificar o gerenciamento de módulos em projetos, facilitando o processo de importação e exportação de código. Permite que os desenvolvedores criem aliases ou “atalhos” para diretórios e arquivos.

É particularmente útil em aplicações de grande porte, devido à complexidade da estrutura de arquivos e pastas, tornando o código mais organizado, fácil de entender e manter.

O problema

Por padrão, o gerenciamento de arquivos dentro de projetos Node.js é feito por meio de caminhos relativos. Isso significa que, ao importar um módulo em um arquivo JavaScript, é necessário especificar o caminho em relação ao arquivo de origem.

Por exemplo, se um arquivo index.js importa um módulo localizado em ./src/shared/file.js , o caminho relativo seria ../../share//file.js. Em projetos maiores, com muitos arquivos e diretórios, o gerenciamento por caminhos relativos torna-se uma tarefa complexa, além disso, pode ser difícil entender a hierarquia e localização dos módulos.

A solução

É aí que entra o path mapping. No lugar de caminhos relativos, é possível criar aliases para os caminhos dos módulos, que podem ser usados para substituir os caminhos completos na importação de arquivos JavaScript. Essa abordagem torna o processo de gerenciamento mais simples e organizado.

Veja, por exemplo, um cenário onde temos a seguinte estrutura de arquivos:

Com o gerenciamento padrão do Node.js, para importar o módulo cpf-validator.js dentro de get-cpf-details.js, você precisaria usar um caminho relativo, como:

Com a utilização de path mapping a importação fica bem mais simples:

Como funciona?

Por meio da definição de um objeto imports no arquivo package.json. Esse objeto é usado para definir o caminho para os módulos no projeto.

Por exemplo, se quisermos definir um alias para o caminho ./src/infra/ , podemos adicionar a seguinte entrada no arquivo package.json:

Essa entrada define um alias para todos os módulos que começam com #infra/ . O caminho correspondente a esses módulos é ./src/infra/*.js.

Com essa definição em vigor, podemos importar o arquivo database.js usando #infra/database.js em vez do caminho relativo:

Como configurar

Para configurar o path mapping em um projeto Node.js é necessário criar o arquivo package.json. Em seguida, é necessário adicionar um objeto imports ao arquivo, incluindo as definições de aliases para caminhos de módulos.

Por exemplo, podemos criar o objeto imports com a seguinte definição de aliases:

Observações

Para pacotes com um pequeno número de exportações ou importações, recomenda-se listar explicitamente cada entrada de subcaminho de exportação. Mas para pacotes que possuem um grande número de subcaminhos, isso pode causar problemas de manutenção e sobrecarga do package.json. Para esses casos de uso, os padrões de exportação de subcaminho podem ser usados.

Seja abaixo uma tabela com as versões do Node.js que suportam oficialmente essa configuração:

Conclusão

O path mapping é uma técnica útil para simplificar o gerenciamento de módulos em projetos Node.js. Ao definir aliases para caminhos de módulos ganha-se uma série de benefícios, como a redução do uso de caminhos relativos, a facilidade de manutenção do código, a melhoria da organização do código e a facilidade de migração de código para outros diretórios ou sistemas.

E aí, bora colocar em prática?

#NeverStopLearning