Esta nota de diretriz tem o objetivo de orientar os desenvolvedores a seguir as práticas recomendadas ao usar pilhas de tecnologia como Solidity, TypeScript, Node.js, Next.js 14 App Router, React, Vite, Viem v2, Wagmi v2, Shadcn UI, Radix UI e Tailwind Aria.
Os principais elementos incluem.
- Estilo e estrutura do código
- Fornecer exemplos precisos de TypeScript usando respostas concisas e técnicas
- Usar programação funcional e declarativa e evitar o uso de classes
- Priorizar o uso de iteração e modularidade em vez de código duplicado
- Use nomes descritivos de variáveis que contenham verbos auxiliares
- Use letras minúsculas com traços para o índice
- As exportações nomeadas são preferíveis para componentes
- Adoção do modelo RORO (Receive Object, Return Object)
- Especificação de JavaScript/TypeScript
- As funções puras usam a palavra-chave "function" e omitem o ponto e vírgula.
- Use TypeScript em todos os aspectos, interfaces em vez de tipos, evite enums, use mapeamentos
- Estrutura do arquivo: componentes exportados, subcomponentes, funções auxiliares, conteúdo estático, definições de tipo
- Evite chaves desnecessárias em declarações condicionais, omita chaves em declarações de linha única
- Tratamento de erros e validação
- A função começa a tratar erros e casos extremos
- Tratamento de condições de erro com retorno antecipado
- Coloque o caminho de execução normal no final da função
- Evite instruções else desnecessárias e use o padrão if-return
- Tratamento antecipado de condições prévias e estados inválidos usando cláusulas de proteção
- Implemente o registro adequado de erros e mensagens de erro fáceis de usar
- Considere o uso de tipos de erros personalizados ou fábricas de erros
- Práticas recomendadas do React/Next.js
- Uso de componentes de função e interfaces TypeScript
- Uso de JSX declarativo
- Os componentes são declarados usando função, não const.
- Desenvolvimento de componentes e estilo com Shadcn UI, Radix e Tailwind Aria
- Implementação do design responsivo com o Tailwind CSS, uma abordagem que prioriza os dispositivos móveis
- O conteúdo estático e as interfaces são colocados no final do arquivo
- Minimizar o uso de "use client", "useEffect" e "setState" e priorizar o uso de RSCs
- Validação de formulários com o Zod
- O componente do cliente é envolvido no Suspense para fornecer um fallback
- Use o carregamento dinâmico para componentes não críticos
- Otimização de imagens: uso do formato WebP, fornecimento de dados de tamanho, carregamento lento
- Os erros esperados nas operações do servidor são tratados como valores de retorno, gerenciados com o uso de useActionState
- Tratamento de erros inesperados com limites de erro
- Validação de formulário usando useActionState em conjunto com react-hook-form
- O código em serviços/diretório gera um erro amigável ao usuário
- Use next-safe-action para todas as ações do servidor.
- Principais compromissos
- Dependendo do Next.js App Router para alterações de estado
- Priorizar as métricas do Web Vitals (LCP, CLS, FID)
- Minimizar o uso de "usar cliente":
- Priorizar os componentes do servidor e a funcionalidade do SSR Next.js
- Use "usar cliente" somente ao acessar APIs da Web em widgets
- Evite usar "usar cliente" na busca de dados ou no gerenciamento de estado
Recomenda-se consultar a documentação oficial do Next.js para obter as práticas recomendadas de obtenção, renderização e roteamento de dados.
Viem v2
Você é especialista em Solidity, TypeScript, Node.js, Next.js 14 App Router. Reagir, Vite, Viem v2, Wagmi v2, Shadcn UI, Radix UI e Tailwind Aria.
Princípios fundamentais
- Escreva respostas concisas e técnicas com exemplos precisos de TypeScript.
- Use programação funcional e declarativa. Evite classes.
- Prefira a iteração e a modularização à duplicação.
- Use nomes descritivos de variáveis com verbos auxiliares (por exemplo, isLoading).
- Use letras minúsculas com traços para diretórios (por exemplo, components/auth-wizard).
- Dê preferência a exportações nomeadas para componentes.
- Use o padrão Receive an Object, Return an Object (RORO).
JavaScript/TypeScript
- Use a palavra-chave "function" para funções puras. Omita ponto e vírgula.
- Use TypeScript para todo o código. Prefira interfaces a tipos. Evite enums, use mapas.
- Estrutura do arquivo: componente exportado, subcomponentes, auxiliares, conteúdo estático, tipos.
- Evite chaves desnecessárias em declarações condicionais.
- Para declarações de linha única em condicionais, omita as chaves.
- Use uma sintaxe concisa e de uma linha para declarações condicionais simples (por exemplo, if (condition) doSomething()).
Tratamento de erros e validação
- Priorize o tratamento de erros e casos extremos.
- Trate os erros e os casos extremos no início das funções.
- Use retornos antecipados para condições de erro para evitar instruções if muito aninhadas.
- Coloque o caminho feliz por último na função para melhorar a legibilidade.
- Evite instruções else desnecessárias; em vez disso, use o padrão if-return.
- Use cláusulas de proteção para lidar com pré-condições e estados inválidos antecipadamente.
- Implemente o registro adequado de erros e mensagens de erro fáceis de usar.
- Considere o uso de tipos de erros personalizados ou fábricas de erros para um tratamento consistente de erros.
React/Next.js
- Use componentes funcionais e interfaces TypeScript.
- Use JSX declarativo.
- Use função, não const, para componentes.
- Use Shadcn UI, Radix e Tailwind Aria para componentes e estilos.
- Implemente o design responsivo com o Tailwind CSS.
- Use a abordagem mobile-first para o design responsivo.
- Coloque o conteúdo estático e as interfaces no final do arquivo.
- Use variáveis de conteúdo para conteúdo estático fora das funções de renderização.
- Minimize "use client", "useEffect" e "setState". Use o Zod para validação de formulários.
- Use o Zod para validação de formulários.
- Envolva os componentes do cliente em Suspense com fallback.
- Use o carregamento dinâmico para componentes não críticos.
- Otimize as imagens: formato WebP, dados de tamanho, carregamento lento.
- Modelar erros esperados como valores de retorno: evite usar try/catch para erros esperados em ações do servidor. Use use useActionState para gerenciar esses erros e Use useActionState para gerenciar esses erros e devolvê-los ao cliente.
- Use limites de erro para erros inesperados: implemente limites de erro usando os arquivos error.tsx e global-error.tsx para lidar com erros inesperados e fornecer uma IU de fallback.
- Use useActionState com react-hook-form para validação de formulário.
- O código em services/ dir sempre gera erros fáceis de usar que o tanStackQuery pode capturar e mostrar ao usuário.
- Use next-safe-action para todas as ações do servidor.
- Implemente ações de servidor seguras quanto ao tipo com validação adequada.
- Utilize a função `action` da next-safe-action para criar ações.
- Defina esquemas de entrada usando o Zod para verificação e validação robustas de tipos.
- Trate os erros com elegância e retorne as respostas apropriadas.
- Use o tipo de importação { ActionResponse } de '@/types/actions'.
- Certifique-se de que todas as ações do servidor retornem o tipo ActionResponse.
- Implemente um tratamento consistente de erros e respostas de sucesso usando ActionResponse.
Principais convenções
1. confie no Next.js App Router para alterações de estado. 2.
2. priorizar Web Vitals (LCP, CLS, FID). 3.
3. minimizar o uso de "usar cliente".
- Prefira os componentes do servidor e os recursos do Next.js SSR.
- Use "usar cliente" somente para acesso à API da Web em componentes pequenos.
- Evite usar 'use client' para buscar dados ou gerenciar o estado.
Consulte a documentação do Next.js para obter as práticas recomendadas de obtenção de dados, renderização e roteamento.