📖 Guia de Configuração do Design System

Este documento fornece um passo a passo detalhado para configurar um projeto de Design System do zero, incluindo a instalação de dependências e a configuração do ambiente.

📁 Criando a Estrutura Básica

1️⃣ Inicialização do Projeto

O primeiro passo é criar um arquivo package.json, que armazenará informações sobre o projeto e suas dependências.

Execute o seguinte comando para gerar automaticamente um package.json com configurações padrão:

npm init -y

2️⃣ Instalação do TypeScript

O TypeScript é uma ferramenta essencial para um Design System, pois fornece tipagem estática e maior segurança no código. Para instalá-lo como dependência de desenvolvimento, use:

npm i typescript -D

3️⃣ Configuração do TypeScript

Agora, precisamos configurar o TypeScript. Para isso, gere um arquivo tsconfig.json com configurações padrão:

npx tsc --init

Para testar se a compilação de arquivos TypeScript está funcionando corretamente, utilize:

npx tsc

Isso compilará os arquivos .tsx e .mjs dentro do projeto.

4️⃣ Instalando o Bundler (Tsup)

O tsup é uma ferramenta leve e eficiente para empacotamento de arquivos TypeScript. Ele gera código nos formatos ESM e CJS, além de criar automaticamente os arquivos de definição .d.ts.

Instale o tsup com:

npm i tsup -D

5️⃣ Adicionando Scripts ao package.json

Agora, adicionamos scripts no package.json para facilitar a execução do bundler:

"scripts": {
  "build": "tsup src/index.ts --format esm,cjs --dts"
}

Este comando criará a pasta dist/ contendo os arquivos gerados a partir do código TypeScript.

⚙️ Configurando o TypeScript

Para garantir que o TypeScript funcione corretamente no projeto, utilize as seguintes configurações no tsconfig.json:

{
  "compilerOptions": {
    "composite": false,
    "declaration": true,
    "declarationMap": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "inlineSources": false,
    "isolatedModules": true,
    "moduleResolution": "node",
    "noUnusedLocals": false,
    "noUnusedParameters": false,
    "preserveWatchOutput": true,
    "skipLibCheck": true,
    "strict": true,
    "jsx": "react-jsx",
    "lib": ["dom", "ES2015"],
    "module": "ESNext",
    "target": "es6"
  },
  "exclude": ["node_modules"],
  "include": ["src"]
}

Isso garante compatibilidade com React e ECMAScript moderno.

🛠 Instalação de Dependências

Como queremos evitar que as dependências do Design System sejam duplicadas no projeto final, devemos instalá-las como devDependencies:

npm i react @types/react @types/react-dom -D

Isso impede que o React seja incluído na build final do Design System, evitando conflitos com os projetos que utilizam a biblioteca.

🔧 Atualização dos Scripts no package.json

Para garantir que o tsup exclua corretamente o React da build e facilite o desenvolvimento, atualizamos os scripts no package.json:

"scripts": {
  "build": "tsup src/index.ts --format esm,cjs --dts --external react",
  "dev": "tsup src/index.ts --format esm,cjs --dts --external react --watch"
}

Isso garante que a biblioteca seja gerada corretamente sem incluir dependências desnecessárias na build.

🔧 Instalação e Configuração do Changeset

O changeset é uma ferramenta para gerenciar versões e changelogs de pacotes. Para instalá-lo, utilize:

npm i @changesets/cli -D

Inicialize o sistema de controle de versões:

npx changeset init

Isso criará a pasta .changeset/, onde ficarão armazenadas as alterações feitas no projeto.

🚀 Deploy do Pacote no npm

No arquivo package.json, é necessário indicar quais arquivos serão usados no build final. Adicione as seguintes entradas para garantir que o pacote tenha uma versão adequada para ambientes CommonJS e ES Modules:

{
  "main": "dist/index.js",
  "module": "dist/index.mjs"
}

"main" aponta para o arquivo gerado no formato CommonJS (.js), usado em ambientes Node.js mais antigos ou projetos que não suportam ES Modules.

"module" aponta para o arquivo gerado no formato ES Module (.mjs), ideal para projetos que utilizam a sintaxe import/export nativa.

O changeset facilita a publicação de novas versões do Design System no npm. O fluxo de publicação segue os passos:

1. Crie um novo registro de alteração:

   npm run changeset

   Isso criará um arquivo dentro da pasta .changeset/ com um resumo das alterações feitas.

2. Atualize a versão do pacote e gere o changelog:

   npm run version-packages

   Esse comando ajusta a versão do package.json e atualiza o changelog do projeto.

3. Publique a nova versão no npm:

   npm run release

   O pacote será publicado de acordo com a versão especificada.

Com esses passos, seu Design System estará configurado e pronto para uso! 🚀