angular-developer

Directrices para desarrolladores de Angular

Cuándo activar

• Trabajar en cualquier proyecto o código base de Angular
• Crear o iniciar un nuevo proyecto, aplicación o librería de Angular
• Generar componentes, servicios, directivas, pipes, guards o resolvers
• Implementar reactividad con Angular Signals, linkedSignal o resource
• Trabajar con formularios Angular (signal forms, formularios reactivos o formularios basados en plantillas)
• Configurar inyección de dependencias, enrutamiento, carga diferida o route guards
• Añadir accesibilidad (ARIA), animaciones o estilos de componentes
• Escribir o depurar pruebas específicas de Angular (unitarias, component harness, E2E)
• Configurar el CLI de Angular o el servidor MCP de Angular

1. Siempre analiza la versión de Angular del proyecto antes de dar orientación, ya que las mejores prácticas y las características disponibles pueden variar significativamente entre versiones. Si creas un nuevo proyecto con Angular CLI, no especifiques una versión a menos que el usuario lo solicite.

2. Al generar código, sigue la guía de estilo de Angular y las mejores prácticas para mantenibilidad y rendimiento. Usa el CLI de Angular para scaffolding de componentes, servicios, directivas, pipes y rutas para garantizar consistencia.

3. Una vez que termines de generar código, ejecuta ng build para asegurarte de que no haya errores de compilación. Si hay errores, analiza los mensajes de error y corrígelos antes de continuar. No omitas este paso, ya que es crítico para garantizar que el código generado sea correcto y funcional.

Crear nuevos proyectos

Si el usuario no proporciona directrices, usa estos valores predeterminados al crear un nuevo proyecto Angular:

1. Usa la versión estable más reciente de Angular a menos que el usuario indique lo contrario.
2. Prefiere Signal Forms para proyectos nuevos solo cuando la versión objetivo de Angular los soporte. Más información.

Reglas de ejecución para ng new: Cuando se te pida crear un nuevo proyecto Angular, debes determinar el comando de ejecución correcto siguiendo estos pasos estrictos:

Paso 1: Verificar si hay una versión explícita del usuario.

• SI el usuario solicita una versión específica (por ejemplo, Angular 15), omite las instalaciones locales y usa estrictamente npx.
• Comando: npx @angular/cli@<requested_version> new <project-name>

Paso 2: Verificar si hay una instalación existente de Angular.

• SI no se solicita una versión específica, ejecuta ng version en la terminal para comprobar si el CLI de Angular ya está instalado en el sistema.
• SI el comando tiene éxito y devuelve una versión instalada, usa la instalación local/global directamente.
• Comando: ng new <project-name>

Paso 3: Recurrir a la última versión.

• SI no se solicita una versión específica Y el comando ng version falla (lo que indica que no existe una instalación de Angular), debes usar npx para obtener la última versión.
• Comando: npx @angular/cli@latest new <project-name>

Componentes

Al trabajar con componentes de Angular, consulta las siguientes referencias según la tarea:

• Fundamentos: Anatomía, metadatos, conceptos básicos y flujo de control en plantillas (@if, @for, @switch). Lee components.md
• Inputs: Inputs basados en señales, transformaciones y model inputs. Lee inputs.md
• Outputs: Outputs basados en señales y mejores prácticas para eventos personalizados. Lee outputs.md
• Elementos anfitrión: Host bindings e inyección de atributos. Lee host-elements.md

Si necesitas documentación más profunda que no se encuentre en las referencias anteriores, lee la documentación en https://angular.dev/guide/components.

Reactividad y gestión de datos

Al gestionar el estado y la reactividad de los datos, usa Angular Signals y consulta las siguientes referencias:

• Resumen de Signals: Conceptos básicos de signal (signal, computed), contextos reactivos y untracked. Lee signals-overview.md
• Estado dependiente (linkedSignal): Crear estado escribible vinculado a señales de origen. Lee linked-signal.md
• Reactividad asíncrona (resource): Obtener datos asíncronos directamente en el estado de señal. Lee resource.md
• Efectos secundarios (effect): Registrar, manipulación del DOM de terceros (afterRenderEffect) y cuándo NO usar efectos. Lee effects.md

Formularios

En la mayoría de los casos para aplicaciones nuevas, prefiere Signal Forms. Al tomar una decisión sobre formularios, analiza el proyecto y considera las siguientes pautas:

• Si la versión de la aplicación soporta Signal Forms y se trata de un formulario nuevo, prefiere Signal Forms.

• Para aplicaciones más antiguas o formularios existentes, usa la estrategia de formularios actual de la aplicación.

• Signal Forms: Usa señales para la gestión del estado del formulario. Lee signal-forms.md

• Formularios basados en plantillas: Úsalos para formularios simples. Lee template-driven-forms.md

• Formularios reactivos: Úsalos para formularios complejos. Lee reactive-forms.md

Inyección de dependencias

Al implementar la inyección de dependencias en Angular, sigue estas pautas:

• Fundamentos: Resumen de la inyección de dependencias, servicios y la función inject(). Lee di-fundamentals.md
• Crear y usar servicios: Crear servicios, la opción providedIn: 'root' e inyectar en componentes u otros servicios. Lee creating-services.md
• Definir proveedores de dependencias: Provisión automática vs manual, InjectionToken, useClass, useValue, useFactory y ámbitos. Lee defining-providers.md
• Contexto de inyección: Dónde está permitido inject(), runInInjectionContext y assertInInjectionContext. Lee injection-context.md
• Inyectores jerárquicos: EnvironmentInjector vs ElementInjector, reglas de resolución, modificadores (optional, skipSelf) y providers vs viewProviders. Lee hierarchical-injectors.md

Angular Aria

Al construir componentes accesibles personalizados para cualquiera de los siguientes patrones: Acordeón, Listbox, Combobox, Menú, Pestañas, Barra de herramientas, Árbol, Cuadrícula, consulta la siguiente referencia:

• Componentes Angular Aria: Construir componentes accesibles sin cabeza (Acordeón, Listbox, Combobox, Menú, Pestañas, Barra de herramientas, Árbol, Cuadrícula) y estilizar atributos ARIA. Lee angular-aria.md

Enrutamiento

Al implementar la navegación en Angular, consulta las siguientes referencias:

• Definir rutas: Rutas URL, segmentos estáticos vs dinámicos, comodines y redirecciones. Lee define-routes.md
• Estrategias de carga de rutas: Carga ansiosa vs diferida, y carga consciente del contexto. Lee loading-strategies.md
• Mostrar rutas con outlets: Usar <router-outlet>, outlets anidados y outlets con nombre. Lee show-routes-with-outlets.md
• Navegar a rutas: Navegación declarativa con RouterLink y navegación programática con Router. Lee navigate-to-routes.md
• Controlar el acceso a rutas con guards: Implementar CanActivate, CanMatch y otros guards para seguridad. Lee route-guards.md
• Resolvedores de datos: Precargar datos antes de la activación de la ruta con ResolveFn. Lee data-resolvers.md
• Ciclo de vida del enrutador y eventos: Orden cronológico de los eventos de navegación y depuración. Lee router-lifecycle.md
• Estrategias de renderizado: CSR, SSG (Prerendering) y SSR con hidratación. Lee rendering-strategies.md
• Animaciones de transición de rutas: Habilitar y personalizar la API de View Transitions. Lee route-animations.md

Si necesitas documentación más profunda o más contexto, visita la guía oficial de enrutamiento de Angular.

Estilos y animaciones

Al implementar estilos y animaciones en Angular, consulta las siguientes referencias:

• Usar Tailwind CSS con Angular: Integrar Tailwind CSS en proyectos Angular. Lee tailwind-css.md
• Animaciones de Angular: Usar CSS nativo (recomendado) o el DSL heredado para efectos dinámicos. Lee angular-animations.md
• Estilizar componentes: Mejores prácticas para estilos de componentes y encapsulación. Lee component-styling.md

Pruebas

Al escribir o actualizar pruebas, consulta las siguientes referencias según la tarea:

• Fundamentos: Mejores prácticas para pruebas unitarias, patrones asíncronos y TestBed. Lee testing-fundamentals.md
• Component Harnesses: Patrones estándar para una interacción robusta con componentes. Lee component-harnesses.md
• Pruebas de enrutador: Usar RouterTestingHarness para pruebas de navegación fiables. Lee router-testing.md
• Pruebas de extremo a extremo (E2E): Mejores prácticas para pruebas E2E con Cypress o Playwright. Lee e2e-testing.md

Herramientas

Al trabajar con herramientas de Angular, consulta las siguientes referencias:

• Angular CLI: Crear aplicaciones, generar código (componentes, rutas, servicios), servir y compilar. Lee cli.md
• Servidor MCP de Angular: Herramientas disponibles, configuración y características experimentales. Lee mcp.md

Anti-patrones

• Usar null o undefined como valores iniciales de campos de formulario signal: usa '', 0 o [] en su lugar
• Acceder a banderas de estado de campos de formulario sin llamar al campo primero: form.field.valid() — usa form.field().valid()
• Iniciar nuevos formularios con APIs de formularios antiguas cuando la versión de Angular objetivo soporta Signal Forms
• Establecer atributos HTML min, max, value, disabled o readonly en entradas [formField] — defínelos como reglas de esquema en su lugar
• Llamar a inject() fuera de un contexto de inyección — usa runInInjectionContext cuando sea necesario
• Usar effect() para estado derivado que debería usar computed()
• Referenciar $parent.$index en bucles @for anidados — Angular no soporta $parent; usa let outerIdx = $index en su lugar

Habilidades relacionadas

• tdd-workflow — flujo de trabajo de desarrollo guiado por pruebas aplicable a componentes y servicios de Angular
• security-review — lista de verificación de seguridad para aplicaciones web, incluidos aspectos específicos de Angular
• frontend-patterns — patrones generales de frontend para contexto sobre enfoques de React/Next.js