Como publicar uma biblioteca de hooks React no npm com Turborepo

Quando você tem duas aplicações React diferentes no mesmo repositório, e elas reaproveitam algum tipo de lógica complexa como usar o serviço de geolocalização, adicionar scripts a página, armazenar dados no localStorage ou sessionStorage, como boa prática você abstrai essa lógica e cria hooks customizados. Certo?.

Mas para não duplicar código nas duas aplicações, o que você faz? É isto que vamos descobrir neste artigo.

Você vai aprender:

• Criar um monorepo utilizando Turborepo.
• Configurar e criar pacotes dentro do monorepo.
• Consumir esses pacotes em diferentes aplicações.
• Publicar os pacotes no npm para uso interno ou externo.

E muito mais. Então vem comigo!

Como otimizar o desenvolvimento

Imagina que você trabalha em um e-commerce. Neste serviço, o usuário precisa preencher seu endereço em algum formulário para calcular a taxa de entrega. Este endereço é preenchido uma vez se o usuário tiver cadastro, mas se não terá que preencher o CEP para calcular a taxa de entrega na tela de produto e de finalização da compra.

Então, como desenvolvedor(a) para facilitar o preenchimento dos dados de endereço do usuário, você cria um hook que a partir do CEP (código de endereçamento postal) ele retorna o endereço completo, preenchendo automaticamente os campos como bairro, município e estado, melhorando a usabilidade da aplicação e experiência do usuário.

Este hook é tão útil nestes cenários que você resolveu compartilhar ele com sua equipe de desenvolvimento.

E para não duplicar o código do hook nas diferentes aplicações desenvolvidas dentro do e-commerce, você decidiu criar um monorepo e compartilhar seu hook como um pacote.

Mas como fazer isso? É o que iremos descobrir.

Como criar o monorepo

Bom, para trabalhar com um único repositório vamos precisar de uma ferramenta que seja confiável e facilite o fluxo de trabalho dentro dele.

Por isso, a escolha óbvia foi o Turborepo. Com o Turborepo, você pode criar, consumir e publicar pacotes, com builds otimizados e uma estrutura modular que favorece a escalabilidade.

E melhor ainda: você pode transformar o seu código em pacotes independentes que podem ser consumidos não apenas dentro do repositório, mas também por outros projetos.

Abra um prompt de comando (cmd) na pasta de sua preferência. Lá você vai digitar o seguinte comando:

Ao pressionar a tecla enter vai pedir para você diga qual gerenciador de pacotes irá usar (npm, yarn, pnpm, etc) e também um nome para o monorepo. Escolha um nome de sua preferência, eu vou escolher library-hooks-react.

Você verá uma mensagem como abaixo:

Agora você pode acessar a pasta que nomeou no passo anterior. E se preferir, pode até abrir ela no seu editor de código. Eu uso o VS Code, então a minha estrutura de arquivos é esta aqui:

O turborepo já cria para a gente uma aplicação com Next.js, ela está dentro da pasta apps.

Na pasta packages são pacotes e dependências que podem ser compartilhados entre as aplicações do mesmo repositório, como componentes de UI, configurações do typescript de lint dos seus projetos.

Duas coisas que podemos fazer neste momento é renomear a propriedade name no package.json para “root-monorepo”, para ficar claro que é da pasta raiz e diferenciar do nome do pacote que iremos publicar (shhh, spoilers…).

Além disso, vamos deletar a pasta apps/docs pois não iremos usá-la aqui.

Com isso, a primeira etapa que era configurar o monorepo foi concluída. Agora vamos tratar de criar o hook que queremos compartilhar. Vamos lá!

Criando a biblioteca de hooks

Precisamos criar um pacote/workspace com os hooks que queremos compartilhar. Para isso, você precisa criar uma pasta dentro da pasta ./packages com um nome de sua escolha. Eu escolhi “hooks-lib”.

Pelo terminal:

Como iremos utilizar o React com Typescript para criar nossa biblioteca de hooks, precisei instalar as dependências do react e os respectivos tipos.

O resultado é uma pasta chamada hooks-lib contendo um package.json e uma pasta node_modules.

Agora precisamos adicionar um tsconfig para criarmos o hook. Então, dentro de hooks-lib eu crio um arquivo tsconfig.json com o seguinte conteúdo:

Lembra que falei que dentro do monorepo conseguimos reutilizar dependências? No código acima temos um exemplo dessa reutilização.

Como o turborepo já cria para a gente toda uma configuração do typescript que fica dentro da pasta ./packages/typescript-config/base.json, extendemos essa configuração no tsconfig.json do nosso pacote. Legal né?

Agora você só precisa reinstalar as dependências para garantir que tudo irá funcionar direitinho. No diretório raiz do projeto, rode o comando: npm install. E prontinho.

Agora precisamos criar o nosso hook. Então dentro de ./packages/hooks-lib eu crio um arquivo index.ts com o seguinte código:

Este arquivo é nosso hook useCep, que a partir de um número de CEP retorna o endereço completo, permitindo o autocomplete de campos de um formulário de endereço, por exemplo.

E agora lá no ./packages/hooks-lib/package.json só precisamos alterar a propriedade main indicando o arquivo que será exportado, no caso o index.ts.

Agora nosso próximo passo será consumir este hook nas aplicações dentro do próprio repositório único. Então vamos fazer isso!

Usando o hook nas aplicações do monorepo

Como o turborepo já criou uma aplicação Next.js para a gente, só vamos fazer alguns ajustes para conseguir usar o hook useCep na aplicação.

1. Vamos renomear a pasta apps/web para apps/next
2. Dentro de ./apps/next/package.json vamos mudar a propriedade name para “next”

Agora se formos no arquivo ./apps/next/app/page.tsx e tentarmos usar o hook useCep, vamos tomar um erro.

Este erro acontece porque não importamos o hook do caminho correto, então precisamos dizer a nossa aplicação que a dependência que ela está procurando está dentro de um pacote, compartilhado do repositório.

Para isso, vamos lá em ./apps/next/package.json nas dependências, vamos importar nosso pacote:

Feito isso, podemos rodar o comando npm install para instalar essa dependência no projeto next. Agora sim já podemos usar nosso hook. Para isso, em ./apps/next/app/page.tsx eu criei o seguinte código:

Agora você tem duas opções:

1. Ou você volta a pasta raiz do projeto e digita o comando npm run dev para subir sua aplicação
2. Você permanece no diretório ./apps/next e digita npm run dev para rodar sua aplicação Next.js

Ambas as opções vão subir sua aplicação Next, com a diferença de que o primeiro comando roda o turbo dev, que dispara um script em cada área de trabalho com um nome específico. É útil quando você quer executar todas as aplicações de uma vez só.

A segunda opção só roda a aplicação Next.js.

Ao subir a aplicação, ela exibe na url http://localhost:3000 um campo de input para digitarmos o CEP, e ao tirar o foco do campo automaticamente um JSON é exibido na página com as informações de endereço do usuário. Legal né?

E está prontinha a nossa biblioteca de hooks. Você pode criar mais hooks, dentro de uma pasta chamada hooks em ./packages/hooks-lib e exportar seus hooks do arquivo index.ts normalmente. Também irá funcionar.

Só tome cuidado na exportação, busque seguir as melhores práticas como adotar o padrão Barrel Export.

Se você não conhece esse padrão de exportação, leia este artigo do Klaus Kazlauskas acessando este link da plataforma Medium.

Só que você não pode deixar que um hook tão interessante e usual fique apenas no seu monorepo, não é? Seu hook pode facilitar a vida de muitos desenvolvedores(as) pelo mundo afora, então o que você pode fazer?

Você pode publicar sua biblioteca de hooks no npm, por exemplo. É isto que iremos fazer agora.

Publicando no npm

Antes de tudo, para você publicar algum pacote no npm você precisa ter uma conta. Se você não tiver uma conta, precisa criar uma. É bem rapidinho, só preencher alguns dados e verificar sua conta através do email.

Outro detalhe super importante aqui é que antes de publicar o pacote você precisa confirmar se o nome que escolheu para o pacote está disponível. Você pode fazer isso digitando no terminal:

Se o nome estiver disponível, você receberá uma mensagem como essa:

E aí você pode usar este nome para o seu pacote. Caso contrário, aparecerão informações sobre a biblioteca existente com o nome que você iria publicar.

Se você escolheu um nome não disponível, pode mudar o nome do seu pacote trocando a propriedade name em ./packages/hooks-lib/package.json para o nome disponível que você encontrar.

Compilando o Typescript para JavaScript

Nossa biblioteca funciona nas aplicações Vite e Next porque ambas compilam o código Typescript para Javascript.

Mas como queremos publicar o pacote de hooks, precisamos compilar o TypeScript para o JavaScript.

Antes de publicar precisamos fazer algumas etapas:

1. Agrupar e compilar o código-fonte para esm e commonjs, para quem instalar o nosso package ser capaz de importá-lo;
2. Configurar um script de desenvolvimento para desenvolvimento local;
3. Publicar no NPM; 3.1. Realizar o controle de versionamento; 3.2. Realizar o controle de publicação.

Para compilar nosso código TS para JS vamos utilizar o tsup.

O tsup é uma ferramenta de empacotamento e compilação de TypeScript que gera bundles em formatos como CJS e ESM, além de criar arquivos de declaração de tipos (.d.ts).

Ele oferece uma configuração simples e performance rápida, ideal para bibliotecas e projetos que compartilham um único repositório.

Precisamos ir na pasta ./packages/hooks-lib e digitar no terminal

Agora, precisamos criar uma pasta src e mover o arquivo index.ts para dentro dela. E como parte de criar um script de desenvolvimento local, vamos no package.json do hooks-lib (./packages/hooks-lib/package.json) e adicionamos este script:

Este script, vai usar tsup para agrupar e compilar nosso código, e também saídas de arquivos para o diretório dist.

Agora vamos ajustar o main no ./packages/hooks-lib/package.json, para quem instalar esses pacotes usar a versão empacotada e compilada do código.

Um detalhe importante aqui, é: Não queremos injetar todo o react e as dependências do pacote quando alguém usar a biblioteca de hooks.

Quem usar ela já estará usando o react, então podemos adicionar essas dependências nas dependências por pares, assim:

E antes, os apps importavam diretamente os arquivos .ts e refletiam as alterações que fazíamos na biblioteca automaticamente.

Agora com o tsup, é necessário rodar o build manualmente ao atualizar o código. Esta etapa irá gerar o nosso hook compilado em Javascript, bem como seus tipos.

Agora atualize o package.json em ./packages/hooks-lib/package.json para corrigir.

E o arquivo package.json completo tem essa cara:

Controlando as versões com changeset

Já que estamos publicando no npm a nossa lib, é importante manter sempre um controle de versões conforme ela for crescendo e mudanças forem sendo realizadas, como a adição de novos hooks, melhorias de código, etc.

Para fazer este controle de versão e publicação, vamos usar a biblioteca changesets.

O Changesets é uma ferramenta que automatiza o versionamento e o changelog de pacotes, gerenciando as versões com base nas mudanças realizadas.

Então vamos configurar o changesets no nosso projeto. Começando com a instalação. No terminal, do diretório raiz do projeto (./library-hooks-react) digite:

E agora faça a inicialização do changesets

Você verá uma mensagem como esta:

Agora vamos criar nossas versões. Dentro de ./packages/hooks-lib/package.json mude a versão do seu pacote:

E agora na raiz do monorepo vamos usar o changeset:

Vai aparecer uma sequência de mensagens. A primeira pergunta qual pacote você quer incluir:

Você deve selecionar o pacote em questão com a tecla “espaço” e depois pressionar “enter” para prosseguir.

Selecione o pacote com a versão específica. A sua deve ser também a 0.0.1. Cheque bem isso.

Faça uma pequena descrição dessa primeira versão na etapa seguinte:

Na última etapa você só precisa confirmar:

Você pode rodar o comando npx changeset version para preparar sua versão. Note que após este comando a propriedade version em ./packages/hooks-lib/package.json muda para 1.0.0.

Agora se certifique que dentro de cada workspace, onde tem um arquivo package.json, o valor da propriedade private esteja como true. Isso diz quais pacotes você NÃO QUER publicar.

Agora lembra lá do diretório ./changeset? Precisamos fazer algumas mudanças no config.json dentro deste diretório. Na propriedade access, vamos alterar de restricted para public.

E agora finalmente podemos publicar nossa biblioteca no npm. Rode os comandos abaixo na raiz do seu diretório:

E se tudo correr bem você deve ser capaz de ler esta mensagem no console:

E dessa forma você já tem sua biblioteca de hooks react publicada também no npm.

Agora qualquer pessoa desenvolvedora pode instalar e usar o seu pacote de hooks. Bem maneiro né? Você pode acessar o npm e ver lá no seu perfil, na opção packages o novo pacote que você acabou de publicar.

Conclusão

Compartilhar código por meio de uma biblioteca de hooks em um monorepo com Turborepo, traz benefícios, como reusabilidade e integração entre diferentes aplicações.

Isso facilita a manutenção e acelera o desenvolvimento, permitindo que componentes e lógicas sejam reaproveitados.

E ao publicar no npm esses recursos você colabora com a comunidade React, disponibilizando uma biblioteca que abstrai uma lógica muito usada em diferentes projetos, como o caso do useCep.

Se você quiser se aprofundar em como trabalhar e desenvolver aplicações que compartilham um único repositório, pode acessar o link da formação Construa um Design System com React, Turborepo e Storybook e se você for do time Angular, pode também fazer a formação Angular: cursos para construir um Design System com Nx, Monorepo e Storybook.

Referências

• Publish a Typescript React library to NPM in a monorepo (gratuito, inglês, texto)
• Do a barrel export (gratuito, inglês, texto)
• Documentação do Turborepo (gratuito, inglês/português, texto)
• Changeset repository (gratuito, inglês, texto)
• Monorepo: como usá-lo para desenvolver e integrar grandes projetos (gratuito, português, texto)
• React: desenvolvendo design systems modulares com Turborepo (pago, português, curso/vídeo)

E agora rodar novamente o comando npm install para instalar essa nova dependência.

Com isso, agora você pode usar o hook useCep dentro de sua aplicação com Vite também.

Novamente você pode subir apenas uma aplicação digitando npm run dev do diretório da mesma, ou rodar o npm run dev no diretório raiz e subir ambas as aplicações com next e vite.