angular-developer

Diretrizes para Desenvolvedores Angular

Quando Ativar

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

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

2. Ao gerar código, siga o guia de estilo e as práticas recomendadas do Angular para manter a capacidade de manutenção e o desempenho. Use o Angular CLI para gerar componentes, serviços, diretivas, pipes e rotas, garantindo consistência.

3. Depois 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 é fundamental 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 do Angular de destino 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:

Passo 1: Verificar 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>

Passo 2: Verificar 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>

Passo 3: Recorrer à 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 fluxo de controle de template (@if, @for, @switch). Leia components.md
• Inputs: Inputs baseados em signal, transforms e model inputs. Leia inputs.md
• Outputs: Outputs baseados em signal e práticas recomendadas para eventos personalizados. Leia outputs.md
• Elementos Hospedeiros: Host bindings e injeção de atributos. Leia host-elements.md

Se precisar de documentação mais aprofundada não encontrada 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 Signals do Angular e consulte as seguintes referências:

• Visão Geral dos Signals: Conceitos centrais de signal (signal, computed), contextos reativos e untracked. Leia signals-overview.md
• Estado Dependente (linkedSignal): Criando estado gravável vinculado a source signals. Leia linked-signal.md
• Reatividade Assíncrona (resource): Buscando dados assíncronos diretamente no estado do 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 novo formulário, 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 de formulários. Leia signal-forms.md

• Formulários orientados a 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 Providers 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 e 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 eager vs lazy 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
• Resolvers de Dados: Pré-buscando 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 em 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: Práticas recomendadas para estilos de componentes e encapsulamento. Leia component-styling.md

Testes

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

• Fundamentos: Práticas recomendadas para testes unitários, padrões assíncronos e TestBed. Leia testing-fundamentals.md
• Harnesses de Componentes: Padrões padrão para interação robusta com componentes. Leia component-harnesses.md
• Testes de Roteador: Usando RouterTestingHarness para testes de navegação confiáveis. Leia router-testing.md
• Testes End-to-End (E2E): Práticas recomendadas 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

Antipadrões

• Usar null ou undefined como valores iniciais de campos de signal forms — use '', 0 ou [] em vez disso
• Acessar flags de estado de campos 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 do Angular de destino suporta Signal Forms
• Definir atributos HTML min, max, value, disabled ou readonly em inputs [formField] — defina-os como regras de esquema
• 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

Skills Relacionadas

• tdd-workflow — fluxo de trabalho de desenvolvimento orientado a testes aplicável a componentes e serviços Angular
• security-review — lista de verificação 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