CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code when working with code in this repository.
4 
5## Overview
6 
7DotCMS Core-Web monorepo — Angular + Nx. Uses **pnpm** as package manager. Nx is not installed globally — always use `pnpm nx`.
8 
9### MCP Servers
10 
11Configured in `/.mcp.json`. Use these instead of guessing:
12 
13- **`angular-cli`** — Angular best practices, documentation search, code examples. Use before writing Angular code.
14- **`primeng`** — PrimeNG component API, props, events, examples. Use when building UI.
15- **`chrome-devtools`** — Browser automation, screenshots, network debugging, performance tracing.
16 
17## Essential Commands
18 
19```bash
20pnpm nx serve dotcms-ui                    # Dev server (proxies /api/* to port 8080)
21pnpm nx build dotcms-ui                    # Build
22pnpm nx test {project}                     # Test specific project
23pnpm nx test {project} --testPathPattern=  # Test specific file
24pnpm nx lint {project}                     # Lint
25pnpm nx affected:test                      # Test only changed projects
26pnpm run test:dotcms                       # Test all
27pnpm run lint:dotcms                       # Lint all
28```
29 
30## Architecture
31 
32### Where Code Goes
33 
34```
35apps/dotcms-ui/              # Main admin UI application
36libs/portlets/               # Feature portlets (new portlets go HERE)
37libs/ui/                     # Shared UI components (multi-portlet)
38libs/data-access/            # Shared services (multi-portlet)
39libs/dotcms-models/          # TypeScript interfaces and types
40libs/edit-content/           # Content editing library
41libs/block-editor/           # TipTap rich text editor
42libs/sdk/                    # External SDKs (client, react, angular)
43```
44 
45### Code Placement Rules
46 
47```
48Is this component/service used by multiple portlets?
49├─ NO  → libs/portlets/{feature}/
50└─ YES → Is it domain-agnostic?
51    ├─ YES (UI)      → libs/ui/
52    ├─ YES (Service)  → libs/data-access/
53    └─ NO             → libs/portlets/shared/ or refactor
54```
55 
56## Angular Rules (REQUIRED)
57 
58### Modern Syntax — Always Use
59 
60```typescript
61// Control flow
62@if (condition()) { <content /> }           // NOT *ngIf
63@for (item of items(); track item.id) { }   // NOT *ngFor
64 
65// Inputs/Outputs
66data = input<string>();                      // NOT @Input()
67onChange = output<string>();                  // NOT @Output()
68 
69// Testing selectors
70<button data-testid="submit-btn">Submit</button>
71spectator.query('[data-testid="submit-btn"]');
72spectator.setInput('prop', value);           // ALWAYS use setInput
73```
74 
75### Component Conventions
76 
77- **Prefix**: All components use `dot-` prefix
78- **Standalone**: All new components must be standalone
79- **State**: Use NgRx signals (`@ngrx/signals`) for state management
80- **Styling**: Tailwind CSS + PrimeNG theme (PrimeFlex deprecated/removed — use Tailwind utilities instead)
81- **Testing**: Jest + Spectator, use `data-testid` for selectors
82- **Dialogs**: All dialogs must have `closable: true` and `closeOnEscape: true` to allow closing via X button and ESC key
83 
84### Form Markup
85 
86Always wrap form fields with this structure for consistent styling:
87 
88```html
89<form class="form">
90  <div class="field">
91    <label for="name">Name</label>
92    <input pInputText id="name" />
93  </div>
94  <div class="field">
95    <label for="site">Site</label>
96    <p-select id="site" [options]="sites()" />
97  </div>
98</form>
99```
100 
101## Portlet Development
102 
103New portlets go in `libs/portlets/`. For full patterns, architecture, testing, and Nx generator setup:
104 
105> **See [`libs/portlets/CLAUDE.md`](libs/portlets/CLAUDE.md)** — the complete portlet development guide with `dot-tags` as canonical reference.
106 
107## Testing (Jest + Spectator)
108 
109### Config
110 
111- Use `dot-content-drive` portlet as reference for test config
112- `tsconfig.spec.json` tsconfig.spec.json must have "isolatedModules": true in compilerOptions
113- `tsconfig.json` — do NOT add `"strict": true` or `"module": "preserve"`
114- `tsconfig.spec.json` — keep minimal (only `module`, `target`, `types`)
115- Import `mockProvider` from `@openng/spectator/jest` (not `@openng/spectator`)
116 
117### SignalStore Tests
118 
119- Use `createServiceFactory` from Spectator
120- Call `spectator.flushEffects()` in `beforeEach` to trigger the `withHooks` `onInit` effect
121- Mock services with `mockProvider(Service, { method: jest.fn().mockReturnValue(of(...)) })`
122- Test error paths: mock service to `throwError(() => error)`, assert `httpErrorManager.handle` was called
123- For `jest.mock()` of utilities: place the mock **before** the import
124 
125### Component Tests (with Mocked Store)
126 
127- Use `createComponentFactory` from Spectator
128- Store goes in `componentProviders` (component-level injection), not `providers`
129- Mock all signal getters as `jest.fn().mockReturnValue(...)` and all methods as `jest.fn()`
130- PrimeNG button clicks: `spectator.query(byTestId('btn'))?.querySelector('button')` then `spectator.click(el)`
131 
132### Dialog Tests
133 
134- Mock `DialogService.open` to return `{ onClose: new Subject() }`, then emit a value and complete the subject
135- Two `describe` blocks for create/edit dialog: one with `DynamicDialogConfig.data: {}`, one with `data: { item }`
136- Test that dialogs are configured with `closable: true` and `closeOnEscape: true`
137 
138### DotSiteComponent Mocking
139 
140- Use `jest.mock('@dotcms/ui', ...)` with a stub implementing `ControlValueAccessor`
141- Add `CUSTOM_ELEMENTS_SCHEMA` when mocking complex child components
142 
143### Debounce / Timer Tests
144 
145- Use `jest.useFakeTimers()` in `beforeEach`, `jest.useRealTimers()` in `afterEach`
146- Advance with `jest.advanceTimersByTime(300)` to trigger debounced actions
147 
148## Backend Integration
149 
150- Dev proxy: `proxy-dev.conf.mjs` routes `/api/*` to port 8080
151- API services: `libs/data-access/` via `DotHttpService`
152- OpenAPI spec: Use `http://localhost:8080/api/openapi.json` (local dev instance), fallback to `https://demo.dotcms.com/api/openapi.json`. Fetch this to understand available endpoints, request/response schemas, and parameters before building API integrations.
153 
154## For Backend/Java Development
155 
156See **[../CLAUDE.md](../CLAUDE.md)** for Java, Maven, REST API, and Git workflow standards.
157 
158<!-- nx configuration start-->
159<!-- Leave the start & end comments to automatically receive updates. -->
160 
161## General Guidelines for working with Nx
162 
163- For navigating/exploring the workspace, invoke the `nx-workspace` skill first - it has patterns for querying projects, targets, and dependencies
164- When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task through `nx` (i.e. `nx run`, `nx run-many`, `nx affected`) instead of using the underlying tooling directly
165- Prefix nx commands with the workspace's package manager (e.g., `pnpm nx build`, `npm exec nx test`) - avoids using globally installed CLI
166- You have access to the Nx MCP server and its tools, use them to help the user
167- For Nx plugin best practices, check `node_modules/@nx/<plugin>/PLUGIN.md`. Not all plugins have this file - proceed without it if unavailable.
168- NEVER guess CLI flags - always check nx_docs or `--help` first when unsure
169 
170## Scaffolding & Generators
171 
172- For scaffolding tasks (creating apps, libs, project structure, setup), ALWAYS invoke the `nx-generate` skill FIRST before exploring or calling MCP tools
173 
174## When to use nx_docs
175 
176- USE for: advanced config options, unfamiliar flags, migration guides, plugin configuration, edge cases
177- DON'T USE for: basic generator syntax (`nx g @nx/react:app`), standard commands, things you already know
178- The `nx-generate` skill handles generator discovery internally - don't call nx_docs just to look up generator syntax
179 
180<!-- nx configuration end-->
181