writing-client-code

### Why `libs/common` cannot import Angular CLI is a first-class client. Any code in `libs/common` must work without Angular's dependency injection, decorators, or lifecycle hooks. This is why cross-client services use abstract classes as interfaces — the concrete implementations (`Default*`, `Web*`, `Browser*`, `Desktop*`, `Cli*`) live in their respective apps. ## Architectural Rationale ### Thin components Components contain only view logic. Business logic belongs in services. This keeps components testable, reusable, and prevents Angular lifecycle coupling from leaking into domain logic. ### Composition over inheritance Avoid extending components across clients. Compose using shared child components instead. Inheritance creates tight coupling between client-specific UI and shared behavior — when one client's needs diverge, inherited components become hard to change safely. ### Don't modernize existing code unless asked The codebase contains both legacy and modern Angular patterns. When modifying an existing file, **follow the patterns already in that file**. Don't migrate any of these unless explicitly asked: - `*ngIf` → `@if`, `*ngFor` → `@for` - `@Input()` / `@Output()` → `input()` / `output()` signals - Constructor injection → `inject()` - Default change detection → `OnPush` - NgModule declarations → standalone components If asked to modernize, follow this order (per the Angular migration guide): standalone → control flow → input/output signals → view queries → signals → computed → OnPush (last, only after full signal migration). ### State management: Signals vs RxJS - **Component local state and Angular-only services:** Use Signals - **Cross-client services (`libs/common`):** Use RxJS (because CLI has no Angular Signals support) Avoid manual subscriptions. Prefer `| async` pipe. When subscriptions are necessary, pipe through `takeUntilDestroyed()` — enforced by the `prefer-takeUntil` lint rule. ### No TypeScript enums (ADR-0025) Use frozen const objects with `Object.freeze()` and `as const`, plus a companion type alias. Enums have runtime behavior that creates subtle bugs with tree-shaking. ## Critical Rules for New Code These rules apply **strictly to new files and components**. For existing code, follow the patterns already in the file. - **New components must use `ChangeDetectionStrategy.OnPush`** and be `standalone: true`. `NgModules` are permitted only for grouping related standalone components - **Prefer `inject()` function** for DI in Angular primitives (components, pipes, directives). Use constructor injection for code shared with non-Angular clients (CLI) - **New templates must use control flow syntax** (`@if`, `@for`, `@switch`), not structural directives - **Use `host` property** in component decorators, not `@HostBinding` / `@HostListener` - **Use Reactive Forms exclusively** — not template-driven forms - **File naming:** `kebab-case.component.ts`, `.service.ts`, `.pipe.ts`, `.directive.ts`. Also: `.request.ts`, `.response.ts`, `.view.ts`, `.data.ts` for models (ADR-0012) - **All Tailwind classes require `tw-` prefix** — `tw-flex`, `tw-mt-2`, not `flex`, `mt-2` - **Testing with Jest** — use `jest-mock-extended` for mocking services. `describe`/`it` blocks, not `test()` - **Imports from `@bitwarden/common`** must not pull in Angular-specific code (breaks CLI) ## Examples ### Dependency injection (new Angular code) ```typescript // CORRECT — inject() for Angular primitives export class VaultComponent { private vaultService = inject(VaultService); } // ALSO CORRECT — constructor injection for code shared with CLI export class CryptoService { constructor(private stateService: StateService) {} } ``` ### Tailwind prefix ```html <!-- CORRECT --> <div class="tw-flex tw-gap-2 tw-mt-4"> <!-- WRONG — missing tw- prefix, will be stripped --> <div class="flex gap-2 mt-4"></div> </div> ``` ### Const objects over enums (ADR-0025) ```typescript // CORRECT — with companion type alias export const CipherType = Object.freeze({ Login: 1, SecureNote: 2, } as const); export type CipherType = (typeof CipherType)[keyof typeof CipherType]; // WRONG — TypeScript enums have runtime side effects export enum CipherType { Login = 1, SecureNote = 2, } ``` ## Further Reading - [Angular conventions](https://contributing.bitwarden.com/contributing/code-style/web/angular) - [Angular migration guide](https://contributing.bitwarden.com/contributing/code-style/web/angular-migration-guide) - [TypeScript style](https://contributing.bitwarden.com/contributing/code-style/typescript/) - [Component Library](https://contributing.bitwarden.com/contributing/ui/component-library/)