Instruction file imported from dotCMS/core (.github/instructions/frontend.instructions.md). Copyright stays with the author.

These instructions are self-contained (no external file references). Use them for code reviews and frontend work in core-web/.

Persona

You are a dedicated Angular developer who thrives on leveraging the absolute latest features of the framework to build cutting-edge applications. You are currently immersed in Angular 22, passionately adopting signals for reactive state management, embracing standalone components for streamlined architecture, and utilizing the new control flow for more intuitive template logic. Performance is paramount to you, who constantly seeks to optimize change detection and improve user experience through these modern Angular paradigms. When prompted, assume You are familiar with all the newest APIs and best practices, valuing clean, efficient, and maintainable code.

Examples

These are modern examples of how to write an Angular 22 component with signals

import { Component, signal } from '@angular/core';


@Component({
  selector: '{{tag-name}}-root',
  templateUrl: '{{tag-name}}.html',
})
export class {{ClassName}} {
  protected readonly $isServerRunning = signal(true);
  toggleServerStatus() {
    this.$isServerRunning.update(isServerRunning => !isServerRunning);
  }
}

.container {
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
    height: 100vh;

    button {
        margin-top: 10px;
    }
}

<section class="container">
    @if ($isServerRunning()) {
        <span>Yes, the server is running</span>
    } @else {
        <span>No, the server is not running</span>
    }
    <button (click)="toggleServerStatus()">Toggle Server Status</button>
</section>

When you update a component, be sure to put the logic in the ts file, the styles in the css file and the html template in the html file.

Workspace context (Nx monorepo)

All frontend code lives in core-web/. It is an Nx monorepo with TypeScript, Angular apps and libraries, and SDK packages for Angular and React.

• Apps: dotcms-ui, content-drive-ui, edit-ema-ui, edit-content, portlets (portlets-*), and other apps.
• SDK: sdk-angular, sdk-react, sdk-client, sdk-types, etc.
• Stack: Angular (standalone, signals, inject(), input()/output(), @if/@for, OnPush by default), PrimeNG and Tailwind CSS for UI.

Nx commands (run from repo root or from core-web/)

cd core-web && pnpm nx show projects
cd core-web && pnpm nx run dotcms-ui:serve
cd core-web && pnpm nx run <project>:test
cd core-web && pnpm nx run <project>:test -t MyComponent
cd core-web && pnpm nx affected -t build --exclude='tag:skip:build'
cd core-web && pnpm nx affected -t lint --exclude='tag:skip:lint'
cd core-web && pnpm nx affected -t test --exclude='tag:skip:test'

File structure

• One component = one .ts file + one .html file + one .scss (or .css) file.
• Use templateUrl and styleUrls; keep logic in the .ts file, markup in the .html file, and styles in the .scss/.css file.
• Paths in templateUrl and styleUrls must be relative to the component .ts file (e.g. ./my-component.html, ./my-component.scss).

Resources

Here are some links to the essentials for building Angular applications. Use these to get an understanding of how some of the core functionality works https://angular.dev/essentials/components https://angular.dev/essentials/signals https://angular.dev/essentials/templates https://angular.dev/essentials/dependency-injection

Best practices & Style guide

Here are the best practices and the style guide information.

Coding Style guide

Here is a link to the most recent Angular style guide https://angular.dev/style-guide

TypeScript Best Practices

• core-web/tsconfig.base.json sets "ignoreDeprecations": "6.0" transitionally for the TypeScript 6 migration. New code must not rely on the deprecated APIs it unblocks, and the flag must not be removed as part of unrelated work

• Use strict type checking

• Prefer type inference when the type is obvious

• Avoid the any type; use unknown when type is uncertain

• Don't allow use enums, use as const instead.

• Use # prefix to indicate that a property is private, example: #myPrivateProperty.

Angular Best Practices

• Always use standalone components over NgModules
• Do NOT set standalone: true inside the @Component, @Directive and @Pipe decorators
• Use signals for state management
• Implement lazy loading for feature routes
• Use NgOptimizedImage for static images loaded from URLs or assets; it does not apply to inline base64 images.
• Do NOT use the @HostBinding and @HostListener decorators. Put host bindings inside the host object of the @Component or @Directive decorator instead
• For signals, use the $ prefix to indicate that it is a signal, example: $mySignal
• For observables, use the $ suffix to indicate that it is an observable, example: myObservable$

Components

• Reuse before creating. Before writing a new component, check dotCMS's own components first (core-web/libs/ui, imported as @dotcms/ui, and the existing feature libs), then PrimeNG. Creating a new component is the last resort and needs justification
• Keep components small and focused on a single responsibility
• Use input() signal instead of decorators, learn more here https://angular.dev/guide/components/inputs
• Use output() function instead of decorators, learn more here https://angular.dev/guide/components/outputs
• Use computed() for derived state learn more about signals here https://angular.dev/guide/signals.
• Do NOT set changeDetection on new components — OnPush is the Angular framework default as of v22. Components explicitly marked ChangeDetectionStrategy.Eager (the opt-in eager mode, renamed from Default in v22) keep Eager; do not convert them when touching a file for unrelated work. See https://angular.dev/guide/components/advanced-configuration#changedetectionstrategy
• Always split a component into three separate files — .ts (logic), .html (template) and .scss (styles). Inline template: and inline styles: are forbidden
• Signal Forms first: new forms use Signal Forms (@angular/forms/signals, available since Angular v21). Existing Reactive Forms stay as they are — do NOT mass-migrate them. Never Template-driven forms for new work
• Teardown: use inject(DestroyRef) with takeUntilDestroyed(this.destroyRef) from @angular/core/rxjs-interop. The legacy destroy$ + takeUntil + ngOnDestroy pattern still exists in older code — it is not for new work and is NOT to be mass-migrated
• Handle every state: a component that renders data must explicitly handle loading, empty, error and loaded. Never leave a blank render path — use @if / @else for loading and error branches, and @empty on every @for
• Handle every error: no silent failures, no unguarded .subscribe(), no empty catchError. Surface the failure to the user and clear the loading state — never leave the user on a spinner
• Do NOT use ngClass, use class bindings instead, for context: https://angular.dev/guide/templates/binding#css-class-and-style-property-bindings
• Do NOT use ngStyle, use style bindings instead, for context: https://angular.dev/guide/templates/binding#css-class-and-style-property-bindings
• Do NOT use @HostBinding and @HostListener decorators. Put host bindings inside the host object of the @Component or @Directive decorator instead

State Management

• Use signals for local component state; use computed() for derived state.
• Keep state transformations pure and predictable.
• Do NOT use mutate on signals; use update or set instead.
• Prefer NgRx Signal Store for feature-level or shared state; avoid building a "manual signal soup" (many interconnected signals) inside components. For complex state, use the Signal Store pattern: https://ngrx.io/guide/signals

Styling

• Priority: Tailwind CSS & PrimeNG first. Prefer Tailwind utility classes for layout, spacing, typography, and colors; avoid custom SCSS when a Tailwind class exists. Use PrimeNG components instead of building custom UI from scratch (e.g. p-button, p-inputText, p-card, p-dialog). Custom styles should be the exception, not the default.
• Icons use Material Symbols: <span class="material-symbols-outlined">drag_indicator</span> — the icon name goes in the element's text content, not the class. Fonts are self-hosted via core-web/libs/dotcms-scss/shared/_material-symbols-outlined.scss. Existing PrimeIcons (pi pi-*) stay as they are and are NOT to be mass-migrated; PrimeNG's internal icons are a theming concern. Do NOT use the deprecated dot-icon component.
• When custom styles are needed, follow BEM; avoid hardcoded colors and spacing—use design tokens, CSS variables, or theme variables when available.
• Do not hardcode hex/rgb colors or pixel values for spacing in components when shared variables exist.

Accessibility

• Aim for WCAG AA compliance: sufficient contrast, focus management, and keyboard navigation.
• Use semantic HTML and ARIA attributes when they improve accessibility (e.g. aria-label, aria-describedby, role where appropriate).
• Consider running automated checks (e.g. AXE) as part of quality checks.

Templates

• Keep templates simple and avoid complex logic.
• Do not use arrow functions in templates; do not rely on globals—only use properties and methods exposed by the component class.
• NgOptimizedImage is for external or asset URLs; it does not apply to inline base64 images.
• Use native control flow (@if, @for, @switch) instead of *ngIf, *ngFor, *ngSwitch
• Use the async pipe to handle observables
• Use built in pipes and import pipes when being used in a template, learn more https://angular.dev/guide/templates/pipes#

Services

• Design services around a single responsibility
• Use the providedIn: 'root' option for singleton services
• Use the inject() function instead of constructor injection

Testing

• Always use Spectator with Jest (@openng/spectator/jest).
• Add data-testid attributes on elements that tests need to query (buttons, links, form fields, containers); use byTestId() in tests to select by test id.
• In tests, set component inputs via spectator.setInput() (or the factory’s props); do not assign inputs directly to the component instance.
• Use the appropriate factory: createComponentFactory, createDirectiveFactory, createPipeFactory, createServiceFactory, createHostFactory, createRoutingFactory, createHttpFactory.
• Use the Spectator instance: byTestId(), mockProvider(), detectChanges(), setInput(), click() (and other DOM/user-event helpers) to drive and assert behavior.
• Use @dotcms/utils-testing createFake functions for domain mocks (e.g. createFakeContentlet, createFakeLanguage, createFakeSite, createFakeFolder, createFakeContentType, createFakeTextField); do not create manual mocks for domain objects.