marnixGeerkens/rocketlauncher-claude-code

Diretrizes de Desenvolvimento Frontend

Propósito

Guia abrangente para desenvolvimento React moderno, enfatizando busca de dados baseada em Suspense, lazy loading, organização adequada de arquivos e otimização de performance.

Quando Usar Este Skill

• Criando novos componentes ou páginas
• Construindo novas funcionalidades
• Buscando dados com TanStack Query
• Configurando roteamento com TanStack Router
• Estilizando componentes com MUI v7
• Otimização de performance
• Organizando código frontend
• Melhores práticas TypeScript

---

Início Rápido

Checklist para Novo Componente

Criando um componente? Siga este checklist:

• Use o padrão React.FC<Props> com TypeScript
• Lazy load se componente pesado: React.lazy(() => import())
• Envolva em <SuspenseLoader> para estados de carregamento
• Use useSuspenseQuery para busca de dados
• Aliases de importação: @/, ~types, ~components, ~features
• Estilos: Inline se <100 linhas, arquivo separado se >100 linhas
• Use useCallback para manipuladores de eventos passados para filhos
• Export default no final
• Sem retornos antecipados com spinners de carregamento
• Use useMuiSnackbar para notificações ao usuário

Checklist para Nova Funcionalidade

Criando uma funcionalidade? Configure esta estrutura:

• Crie diretório features/{nome-da-funcionalidade}/
• Crie subdiretórios: api/, components/, hooks/, helpers/, types/
• Crie arquivo de serviço de API: api/{funcionalidade}Api.ts
• Configure tipos TypeScript em types/
• Crie rota em routes/{nome-da-funcionalidade}/index.tsx
• Lazy load componentes da funcionalidade
• Use boundaries Suspense
• Exporte API pública do arquivo index.ts da funcionalidade

---

Referência Rápida de Aliases de Importação

Alias	Resolve Para	Exemplo
@/	src/	import { apiClient } from '@/lib/apiClient'
~types	src/types	import type { User } from '~types/user'
~components	src/components	import { SuspenseLoader } from '~components/SuspenseLoader'
~features	src/features	import { authApi } from '~features/auth'

Definido em: vite.config.ts linhas 180-185

---

Folha de Dicas de Importações Comuns

// React & Lazy Loading
import React, { useState, useCallback, useMemo } from 'react';
const Heavy = React.lazy(() => import('./Heavy'));

// Componentes MUI
import { Box, Paper, Typography, Button, Grid } from '@mui/material';
import type { SxProps, Theme } from '@mui/material';

// TanStack Query (Suspense)
import { useSuspenseQuery, useQueryClient } from '@tanstack/react-query';

// TanStack Router
import { createFileRoute } from '@tanstack/react-router';

// Componentes do Projeto
import { SuspenseLoader } from '~components/SuspenseLoader';

// Hooks
import { useAuth } from '@/hooks/useAuth';
import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';

// Tipos
import type { Post } from '~types/post';

---

Guias por Tópico

🎨 Padrões de Componentes

Componentes React modernos usam:

• React.FC<Props> para segurança de tipos
• React.lazy() para code splitting
• SuspenseLoader para estados de carregamento
• Padrão de const nomeada + export default

Conceitos-chave:

• Lazy load componentes pesados (DataGrid, gráficos, editores)
• Sempre envolva componentes lazy em Suspense
• Use o componente SuspenseLoader (com animação de fade)
• Estrutura do componente: Props → Hooks → Handlers → Render → Export

📖 Guia Completo: resources/component-patterns.md

---

📊 Busca de Dados

PADRÃO PRIMÁRIO: useSuspenseQuery

• Use com boundaries Suspense
• Estratégia cache-first (verifique cache do grid antes da API)
• Substitui verificações isLoading
• Type-safe com genéricos

Camada de Serviço de API:

• Crie features/{funcionalidade}/api/{funcionalidade}Api.ts
• Use instância apiClient do axios
• Métodos centralizados por funcionalidade
• Formato de rota: /form/route (NÃO /api/form/route)

📖 Guia Completo: resources/data-fetching.md

---

📁 Organização de Arquivos

features/ vs components/:

• features/: Específico de domínio (posts, comments, auth)
• components/: Verdadeiramente reutilizável (SuspenseLoader, CustomAppBar)

Subdiretórios de Funcionalidade:

features/
  minha-funcionalidade/
    api/          # Camada de serviço de API
    components/   # Componentes da funcionalidade
    hooks/        # Hooks customizados
    helpers/      # Funções utilitárias
    types/        # Tipos TypeScript

📖 Guia Completo: resources/file-organization.md

---

🎨 Estilização

Inline vs Separado:

• <100 linhas: Inline const styles: Record<string, SxProps<Theme>>

• 100 linhas: Arquivo .styles.ts separado

Método Principal:

• Use prop sx para componentes MUI
• Type-safe com SxProps<Theme>
• Acesso ao tema: (theme) => theme.palette.primary.main

MUI v7 Grid:

<Grid size={{ xs: 12, md: 6 }}>  // ✅ Sintaxe v7
<Grid xs={12} md={6}>             // ❌ Sintaxe antiga

📖 Guia Completo: resources/styling-guide.md

---

🛣️ Roteamento

TanStack Router - Baseado em Pastas:

• Diretório: routes/minha-rota/index.tsx
• Lazy load componentes
• Use createFileRoute
• Dados de breadcrumb no loader

Exemplo:

import { createFileRoute } from '@tanstack/react-router';
import { lazy } from 'react';

const MyPage = lazy(() => import('@/features/minha-funcionalidade/components/MyPage'));

export const Route = createFileRoute('/minha-rota/')({
    component: MyPage,
    loader: () => ({ crumb: 'Minha Rota' }),
});

📖 Guia Completo: resources/routing-guide.md

---

⏳ Estados de Carregamento e Erro

REGRA CRÍTICA: Sem Retornos Antecipados

// ❌ NUNCA - Causa mudança de layout
if (isLoading) {
    return <LoadingSpinner />;
}

// ✅ SEMPRE - Layout consistente
<SuspenseLoader>
    <Content />
</SuspenseLoader>

Por quê: Previne Cumulative Layout Shift (CLS), melhor UX

Tratamento de Erros:

• Use useMuiSnackbar para feedback ao usuário
• NUNCA react-toastify
• Callbacks onError do TanStack Query

📖 Guia Completo: resources/loading-and-error-states.md

---

⚡ Performance

Padrões de Otimização:

• useMemo: Computações caras (filter, sort, map)
• useCallback: Manipuladores de eventos passados para filhos
• React.memo: Componentes caros
• Busca com debounce (300-500ms)
• Prevenção de vazamento de memória (cleanup no useEffect)

📖 Guia Completo: resources/performance.md

---

📘 TypeScript

Padrões:

• Modo estrito, sem tipo any
• Tipos de retorno explícitos em funções
• Importações de tipo: import type { User } from '~types/user'
• Interfaces de props de componentes com JSDoc

📖 Guia Completo: resources/typescript-standards.md

---

🔧 Padrões Comuns

Tópicos Abordados:

• React Hook Form com validação Zod
• Contratos de wrapper DataGrid
• Padrões de componente Dialog
• Hook useAuth para usuário atual
• Padrões de mutação com invalidação de cache

📖 Guia Completo: resources/common-patterns.md

---

📚 Exemplos Completos

Exemplos funcionais completos:

• Componente moderno com todos os padrões
• Estrutura completa de funcionalidade
• Camada de serviço de API
• Rota com lazy loading
• Suspense + useSuspenseQuery
• Formulário com validação

📖 Guia Completo: resources/complete-examples.md

---

Guia de Navegação

Precisa de...	Leia este recurso
Criar um componente	component-patterns.md
Buscar dados	data-fetching.md
Organizar arquivos/pastas	file-organization.md
Estilizar componentes	styling-guide.md
Configurar roteamento	routing-guide.md
Tratar carregamento/erros	loading-and-error-states.md
Otimizar performance	performance.md
Tipos TypeScript	typescript-standards.md
Formulários/Auth/DataGrid	common-patterns.md
Ver exemplos completos	complete-examples.md

---

Princípios Fundamentais

1. Lazy Load Tudo que é Pesado: Rotas, DataGrid, gráficos, editores
2. Suspense para Carregamento: Use SuspenseLoader, não retornos antecipados
3. useSuspenseQuery: Padrão primário de busca de dados para código novo
4. Funcionalidades são Organizadas: Subdiretórios api/, components/, hooks/, helpers/
5. Estilos Baseados no Tamanho: <100 inline, >100 separado
6. Aliases de Importação: Use @/, ~types, ~components, ~features
7. Sem Retornos Antecipados: Previne mudança de layout
8. useMuiSnackbar: Para todas as notificações ao usuário

---

Referência Rápida: Estrutura de Arquivos

src/
  features/
    minha-funcionalidade/
      api/
        minhaFuncionalidadeApi.ts       # Serviço de API
      components/
        MinhaFuncionalidade.tsx         # Componente principal
        SubComponente.tsx               # Componentes relacionados
      hooks/
        useMinhaFuncionalidade.ts       # Hooks customizados
        useSuspenseMinhaFuncionalidade.ts  # Hooks Suspense
      helpers/
        minhaFuncionalidadeHelpers.ts   # Utilitários
      types/
        index.ts                        # Tipos TypeScript
      index.ts                          # Exportações públicas

  components/
    SuspenseLoader/
      SuspenseLoader.tsx                # Loader reutilizável
    CustomAppBar/
      CustomAppBar.tsx                  # Barra de aplicação reutilizável

  routes/
    minha-rota/
      index.tsx                         # Componente de rota
      criar/
        index.tsx                       # Rota aninhada

---

Template de Componente Moderno (Cópia Rápida)

import React, { useState, useCallback } from 'react';
import { Box, Paper } from '@mui/material';
import { useSuspenseQuery } from '@tanstack/react-query';
import { featureApi } from '../api/featureApi';
import type { FeatureData } from '~types/feature';

interface MyComponentProps {
    id: number;
    onAction?: () => void;
}

export const MyComponent: React.FC<MyComponentProps> = ({ id, onAction }) => {
    const [state, setState] = useState<string>('');

    const { data } = useSuspenseQuery({
        queryKey: ['feature', id],
        queryFn: () => featureApi.getFeature(id),
    });

    const handleAction = useCallback(() => {
        setState('updated');
        onAction?.();
    }, [onAction]);

    return (
        <Box sx={{ p: 2 }}>
            <Paper sx={{ p: 3 }}>
                {/* Conteúdo */}
            </Paper>
        </Box>
    );
};

export default MyComponent;

Para exemplos completos, veja resources/complete-examples.md

---

Skills Relacionados

• error-tracking: Rastreamento de erros com Sentry (aplica-se também ao frontend)
• backend-dev-guidelines: Padrões de API backend que o frontend consome

---

Status do Skill: Estrutura modular com carregamento progressivo para gerenciamento de contexto ideal