desarrollador-angular

Directrices para Desarrolladores Angular

Cuándo Activar

• Trabajar en cualquier proyecto o base de código Angular
• Crear o generar un nuevo proyecto, aplicación o biblioteca 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 guards de ruta
• Añadir accesibilidad (ARIA), animaciones o estilos de componentes
• Escribir o depurar pruebas específicas de Angular (unitarias, component harness, E2E)
• Configurar herramientas de Angular CLI o el servidor Angular MCP

1. Siempre analiza la versión de Angular del proyecto antes de proporcionar orientación, ya que las mejores prácticas y las características disponibles pueden variar significativamente entre versiones. Si estás creando 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 mantener la capacidad de mantenimiento y el rendimiento. Usa Angular CLI para generar componentes, servicios, directivas, pipes y rutas para garantizar la coherencia.

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 fundamental para garantizar que el código generado sea correcto y funcional.

Creación de Nuevos Proyectos

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

1. Usa la última versión estable de Angular a menos que el usuario especifique lo contrario.
2. Prefiere Signal Forms para proyectos nuevos solo cuando la versión de Angular objetivo 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 el usuario especifica una versión explícita.

• SI el usuario solicita una versión específica (ej., Angular 15), omite las instalaciones locales y usa estrictamente npx.
• Comando: npx @angular/cli@<versión_solicitada> new <nombre-del-proyecto>

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

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

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 hay instalación Angular), debes usar npx para obtener la última versión.
• Comando: npx @angular/cli@latest new <nombre-del-proyecto>

Componentes

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

• Fundamentos: Anatomía, metadatos, conceptos básicos y flujo de control de 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 datos, usa Angular Signals y consulta las siguientes referencias:

• Resumen de Signals: Conceptos básicos de signals (signal, computed), contextos reactivos y untracked. Lee signals-overview.md
• Estado Dependiente (linkedSignal): Creación de estado escribible vinculado a señales de origen. Lee linked-signal.md
• Reactividad Asíncrona (resource): Obtención de datos asíncronos directamente en el estado de señales. Lee resource.md
• Efectos Secundarios (effect): Registro, 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
• Creación y Uso de Servicios: Creación de servicios, la opción providedIn: 'root' e inyección en componentes u otros servicios. Lee creating-services.md
• Definición de 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: Construcción de componentes accesibles sin cabeza (Acordeón, Listbox, Combobox, Menú, Pestañas, Barra de herramientas, Árbol, Cuadrícula) y estilización de 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 inmediata vs diferida y carga según el contexto. Lee loading-strategies.md
• Mostrar Rutas con Outlets: Uso de <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: Implementación de CanActivate, CanMatch y otros guards para seguridad. Lee route-guards.md
• Resolvedores de Datos: Precarga de 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 (Pre-renderizado) y SSR con hidratación. Lee rendering-strategies.md
• Animaciones de Transición de Rutas: Habilitación y personalización de 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:

• Uso de Tailwind CSS con Angular: Integración de Tailwind CSS en proyectos Angular. Lee tailwind-css.md
• Animaciones Angular: Uso de CSS nativo (recomendado) o el DSL heredado para efectos dinámicos. Lee angular-animations.md
• Estilización de Componentes: Mejores prácticas para estilos de componentes y encapsulamiento. 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: Uso de RouterTestingHarness para pruebas de navegación confiables. 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 Angular, consulta las siguientes referencias:

• Angular CLI: Creación de aplicaciones, generación de código (componentes, rutas, servicios), servicio y compilación. Lee cli.md
• Servidor Angular MCP: Herramientas disponibles, configuración y características experimentales. Lee mcp.md

Antipatrones

• Usar null o undefined como valores iniciales de campos de signal forms — usa '', 0 o [] en su lugar
• Acceder a los indicadores de estado de un campo de formulario sin llamar primero al campo: 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 Angular
• security-review — lista de verificación de seguridad para aplicaciones web, incluyendo aspectos específicos de Angular
• frontend-patterns — patrones generales de frontend para contextualizar enfoques de React/Next.js