Setup de Ambiente

Este guia descreve o processo completo para preparar o ambiente local de desenvolvimento do frontend da Smart NX (SNX).
O objetivo é garantir que todos os desenvolvedores trabalhem com as mesmas configurações, padrões de formatação e qualidade de código, independentemente da IDE utilizada.

💡 A escolha da IDE é livre, mas todas as contribuições devem seguir as convenções oficiais de formatação e linting definidas pelo time de frontend.

---

Pré-requisitos

Antes de iniciar, verifique se possui os seguintes itens configurados:

Requisito	Versão mínima	Observações
Node.js	>=18.x	Utilize a versão LTS estável. Recomendado instalar via Volta ou nvm.
Yarn	>=1.22.x	Gerenciador de pacotes recomendado (suporte também a PNPM ou NPM).
Git	—	Necessário para versionamento e integração com Bitbucket.
Chave SSH	—	Obrigatória para clonar o repositório privado.
VS Code (opcional)	>=1.90	IDE recomendada pela equipe para produtividade e integração com extensões de formatação.

---

Clonando o Repositório

Acesse o repositório privado do Bitbucket:

git clone git@bitbucket.org:smartnx/nx-suite-front-novo.git
cd nx-suite-front-novo

⚠️ Certifique-se de que sua chave SSH está configurada e com permissão no Bitbucket. Caso precise gerar uma nova, siga o guia: 📘 Set up an SSH key — Bitbucket Docs

---

Instalando Dependências

Após o clone, instale as dependências do projeto:

yarn install
# ou, alternativamente:
pnpm install
# ou:
npm install

💡 O uso de Yarn é fortemente recomendado para manter consistência com o ambiente de CI/CD e evitar conflitos de lockfile.

---

Extensões Recomendadas (VS Code)

Embora o uso do VS Code seja opcional, as extensões abaixo são obrigatórias para garantir formatação e padronização do código.

Extensão	Link	Função
Biome	biomejs.biome	Linter, formatter e organizador de imports unificado (substitui ESLint + Prettier).
Import Cost	wix.vscode-import-cost	Exibe o tamanho dos imports em tempo real, ajudando na otimização de bundle.

---

Configuração do Biome

O Biome é o padrão oficial de formatação e linting do projeto. Ele unifica o papel do ESLint, Prettier e Import Organizer em uma ferramenta única e performática.

📄 biome.json (configuração base)

{
  "$schema": "https://biomejs.dev/schemas/1.5.3/schema.json",
  "extends": ["@biomejs/config/strict"],
  "formatter": {
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "linter": {
    "rules": {
      "style": {
        "useConst": "error",
        "noVar": "error",
        "noUnusedVariables": "error"
      },
      "complexity": {
        "noExcessiveNestedBlocks": "warn"
      }
    }
  },
  "organizeImports": {
    "enabled": true
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "double",
      "semicolons": "asNeeded",
      "trailingComma": "es5"
    }
  },
  "typescript": {
    "formatter": {
      "quoteStyle": "double",
      "semicolons": "asNeeded"
    }
  }
}

🔍 Essa configuração assegura código limpo, consistente e legível, de acordo com as boas práticas do ecossistema React + TypeScript.

---

Validação e Formatação

Para verificar e corrigir automaticamente problemas de formatação:

yarn biome check .
yarn biome format .

💡 Ative o Format on Save da sua IDE para aplicar o Biome automaticamente a cada salvamento de arquivo.

---

🔧 Scripts Comuns

Comando	Descrição
yarn dev	Inicia o ambiente de desenvolvimento
yarn build	Gera a build de produção
yarn test	Executa testes unitários
yarn lint	Executa verificação de lint com Biome
yarn format	Formata o código do projeto
yarn storybook	Inicia o ambiente de documentação de componentes

---

💡 Boas Práticas

• Sempre sincronize a branch principal (develop ou main) antes de iniciar novas tarefas.

• Mantenha o Biome atualizado para evitar divergências de estilo.

• Prefira imports absolutos com alias definidos no tsconfig.json.

• Evite usar dependências globais; utilize scripts locais (yarn executa via node_modules/.bin automaticamente).

• Antes de abrir um PR, rode:

  yarn lint && yarn test && yarn build

---

🕓 Histórico de Versões

Data	Versão	Autor / Revisor	Alterações
29/10/2025	v1.0.0	@Matheus Telles	Criação inicial e estrutura base do documento