angular-developer

Diretrizes do Desenvolvedor Angular

Quando Ativar

• Trabalhando em qualquer projeto ou código-fonte Angular
• Criando ou gerando um novo projeto, aplicativo ou biblioteca Angular
• Gerando componentes, serviços, diretivas, pipes, guards ou resolvers
• Implementando reatividade com Angular Signals, linkedSignal ou resource
• Trabalhando com formulários Angular (signal forms, formulários reativos ou baseados em template)
• Configurando injeção de dependência, roteamento, lazy loading ou guards de rota
• Adicionando acessibilidade (ARIA), animações ou estilização de componentes
• Escrevendo ou depurando testes específicos do Angular (unitários, harness de componente, E2E)
• Configurando ferramentas de CLI Angular ou o servidor MCP do Angular

1. Sempre analise a versão do Angular do projeto antes de fornecer orientações, pois as melhores práticas e recursos disponíveis podem variar significativamente entre as versões. Ao criar um novo projeto com o Angular CLI, não especifique uma versão a menos que solicitado pelo usuário.

2. Ao gerar código, siga o guia de estilo Angular e as melhores práticas para manutenibilidade e desempenho. Use o Angular CLI para gerar componentes, serviços, diretivas, pipes e rotas para garantir consistência.

3. Assim que terminar de gerar o código, execute ng build para garantir que não haja erros de build. Se houver erros, analise as mensagens de erro e corrija-os antes de prosseguir. Não pule esta etapa, pois é crítica para garantir que o código gerado esteja correto e funcional.

Criando Novos Projetos

Se nenhuma diretriz for fornecida pelo usuário, use estes padrões ao criar um novo projeto Angular:

1. Use a versão estável mais recente do Angular, a menos que o usuário especifique o contrário.
2. Prefira Signal Forms para novos projetos apenas quando a versão alvo do Angular os suportar. Saiba mais.

Regras de Execução para ng new: Quando solicitado a criar um novo projeto Angular, você deve determinar o comando de execução correto seguindo estas etapas estritas:

Etapa 1: Verifique se há uma versão explícita do usuário.

• SE o usuário solicitar uma versão específica (ex.: Angular 15), ignore as instalações locais e use estritamente npx.
• Comando: npx @angular/cli@<versão_solicitada> new <nome-do-projeto>

Etapa 2: Verifique se há uma instalação Angular existente.

• SE nenhuma versão específica for solicitada, execute ng version no terminal para verificar se o Angular CLI já está instalado no sistema.
• SE o comando for bem-sucedido e retornar uma versão instalada, use a instalação local/global diretamente.
• Comando: ng new <nome-do-projeto>

Etapa 3: Fallback para a versão mais recente.

• SE nenhuma versão específica for solicitada E o comando ng version falhar (indicando que não há instalação Angular), você deve usar npx para obter a versão mais recente.
• Comando: npx @angular/cli@latest new <nome-do-projeto>

Componentes

Ao trabalhar com componentes Angular, consulte as seguintes referências com base na tarefa:

• Fundamentos: Anatomia, metadados, conceitos principais e controle de fluxo de template (@if, @for, @switch). Leia components.md
• Inputs: Inputs baseados em sinal, transformações e model inputs. Leia inputs.md
• Outputs: Outputs baseados em sinal e melhores práticas para eventos personalizados. Leia outputs.md
• Elementos Host: Host bindings e injeção de atributos. Leia host-elements.md

Se precisar de documentação mais aprofundada que não esteja nas referências acima, leia a documentação em https://angular.dev/guide/components.

Reatividade e Gerenciamento de Dados

Ao gerenciar estado e reatividade de dados, use Angular Signals e consulte as seguintes referências:

• Visão Geral de Signals: Conceitos centrais de signal (signal, computed), contextos reativos e untracked. Leia signals-overview.md
• Estado Dependente (linkedSignal): Criando estado gravável vinculado a signals de origem. Leia linked-signal.md
• Reatividade Assíncrona (resource): Buscando dados assíncronos diretamente no estado de signal. Leia resource.md
• Efeitos Colaterais (effect): Logging, manipulação de DOM de terceiros (afterRenderEffect) e quando NÃO usar effects. Leia effects.md

Formulários

Na maioria dos casos para novos aplicativos, prefira signal forms. Ao tomar uma decisão sobre formulários, analise o projeto e considere as seguintes diretrizes:

• Se a versão do aplicativo suportar Signal Forms e este for um formulário novo, prefira signal forms.

• Para aplicativos mais antigos ou formulários existentes, corresponda à estratégia de formulário atual do aplicativo.

• Signal Forms: Use signals para gerenciamento de estado do formulário. Leia signal-forms.md

• Formulários baseados em template: Use para formulários simples. Leia template-driven-forms.md

• Formulários reativos: Use para formulários complexos. Leia reactive-forms.md

Injeção de Dependência

Ao implementar injeção de dependência no Angular, siga estas diretrizes:

• Fundamentos: Visão geral da Injeção de Dependência, serviços e a função inject(). Leia di-fundamentals.md
• Criando e Usando Serviços: Criando serviços, a opção providedIn: 'root' e injetando em componentes ou outros serviços. Leia creating-services.md
• Definindo Provedores de Dependência: Provisão automática vs manual, InjectionToken, useClass, useValue, useFactory e escopos. Leia defining-providers.md
• Contexto de Injeção: Onde inject() é permitido, runInInjectionContext e assertInInjectionContext. Leia injection-context.md
• Injetores Hierárquicos: O EnvironmentInjector vs ElementInjector, regras de resolução, modificadores (optional, skipSelf) e providers vs viewProviders. Leia hierarchical-injectors.md

Angular Aria

Ao construir componentes acessíveis personalizados para qualquer um dos seguintes padrões: Accordion, Listbox, Combobox, Menu, Tabs, Toolbar, Tree, Grid, consulte a seguinte referência:

• Componentes Angular Aria: Construindo componentes acessíveis headless (Accordion, Listbox, Combobox, Menu, Tabs, Toolbar, Tree, Grid) e estilizando atributos ARIA. Leia angular-aria.md

Roteamento

Ao implementar navegação no Angular, consulte as seguintes referências:

• Definir Rotas: Caminhos de URL, segmentos estáticos vs dinâmicos, curingas e redirecionamentos. Leia define-routes.md
• Estratégias de Carregamento de Rotas: Carregamento imediato vs lazy loading e carregamento sensível ao contexto. Leia loading-strategies.md
• Exibir Rotas com Outlets: Usando <router-outlet>, outlets aninhados e outlets nomeados. Leia show-routes-with-outlets.md
• Navegar para Rotas: Navegação declarativa com RouterLink e navegação programática com Router. Leia navigate-to-routes.md
• Controlar Acesso a Rotas com Guards: Implementando CanActivate, CanMatch e outros guards para segurança. Leia route-guards.md
• Resolvedores de Dados: Pré-carregamento de dados antes da ativação da rota com ResolveFn. Leia data-resolvers.md
• Ciclo de Vida e Eventos do Roteador: Ordem cronológica dos eventos de navegação e depuração. Leia router-lifecycle.md
• Estratégias de Renderização: CSR, SSG (Pré-renderização) e SSR com hidratação. Leia rendering-strategies.md
• Animações de Transição de Rota: Habilitando e personalizando a API View Transitions. Leia route-animations.md

Se precisar de documentação mais aprofundada ou mais contexto, visite o guia oficial de Roteamento Angular.

Estilização e Animações

Ao implementar estilização e animações no Angular, consulte as seguintes referências:

• Usando Tailwind CSS com Angular: Integrando Tailwind CSS a projetos Angular. Leia tailwind-css.md
• Animações Angular: Usando CSS nativo (recomendado) ou o DSL legado para efeitos dinâmicos. Leia angular-animations.md
• Estilizando componentes: Melhores práticas para estilos de componente e encapsulamento. Leia component-styling.md

Testes

Ao escrever ou atualizar testes, consulte as seguintes referências com base na tarefa:

• Fundamentos: Melhores práticas para testes unitários, padrões assíncronos e TestBed. Leia testing-fundamentals.md
• Harnesses de Componente: Padrões padrão para interação robusta com componentes. Leia component-harnesses.md
• Teste de Roteador: Usando RouterTestingHarness para testes de navegação confiáveis. Leia router-testing.md
• Testes End-to-End (E2E): Melhores práticas para testes E2E com Cypress ou Playwright. Leia e2e-testing.md

Ferramentas

Ao trabalhar com ferramentas Angular, consulte as seguintes referências:

• Angular CLI: Criando aplicativos, gerando código (componentes, rotas, serviços), servindo e construindo. Leia cli.md
• Servidor MCP Angular: Ferramentas disponíveis, configuração e recursos experimentais. Leia mcp.md

Anti-Padrões

• Usar null ou undefined como valores iniciais de campos de formulário signal — use '', 0 ou [] em vez disso
• Acessar flags de estado de campo de formulário sem chamar o campo primeiro: form.field.valid() — use form.field().valid()
• Iniciar novos formulários com APIs de formulário mais antigas quando a versão alvo do Angular suportar Signal Forms
• Definir atributos HTML min, max, value, disabled ou readonly em inputs [formField] — defina-os como regras de schema
• Chamar inject() fora de um contexto de injeção — use runInInjectionContext quando necessário
• Usar effect() para estado derivado que deveria usar computed()
• Referenciar $parent.$index em loops @for aninhados — Angular não suporta $parent; use let outerIdx = $index em vez disso

Habilidades Relacionadas

• tdd-workflow — fluxo de trabalho de desenvolvimento orientado a testes aplicável a componentes e serviços Angular
• security-review — checklist de segurança para aplicações web, incluindo preocupações específicas do Angular
• frontend-patterns — padrões gerais de frontend para contexto sobre abordagens React/Next.js