CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Project Overview
6 
7This is the **DotCMS Client SDK** (`@dotcms/client`) - a JavaScript/TypeScript library for interacting with DotCMS REST APIs. The SDK is part of a larger DotCMS monorepo and serves as the foundation for framework-specific integrations (React, Angular, etc.).
8 
9## Essential Commands
10 
11### Development Commands
12```bash
13# Install dependencies (from monorepo root)
14yarn install
15 
16# Build library for distribution
17nx run sdk-client:build                  # ESM/CJS dual package build
18nx run sdk-client:build:js               # Specialized esbuild for editor integration
19 
20# Run tests
21nx run sdk-client:test                   # Run Jest tests
22nx run sdk-client:test:ci                # Run tests with CI configuration and coverage
23 
24# Code quality
25nx run sdk-client:lint                   # ESLint code linting
26 
27# Publishing
28nx run sdk-client:publish --args.ver=1.0.0 --args.tag=latest
29```
30 
31### Testing Commands
32```bash
33# Run specific test file
34nx test sdk-client --testNamePattern="specific test name"
35 
36# Run tests in watch mode
37nx test sdk-client --watch
38 
39# Run tests with coverage
40nx test sdk-client --coverage
41```
42 
43## Architecture Overview
44 
45### Project Structure
46```
47libs/sdk/client/
48├── src/
49│   ├── index.ts                    # Main export (createDotCMSClient)
50│   ├── internal.ts                 # Internal utilities for other SDKs
51│   └── lib/
52│       ├── client/
53│       │   ├── client.ts          # Main DotCMSClient class
54│       │   ├── content/           # Content API with query builders
55│       │   ├── navigation/        # Navigation API
56│       │   ├── page/             # Page API with GraphQL support
57│       │   └── models/           # TypeScript interfaces and types
58│       └── utils/
59│           └── graphql/          # GraphQL utilities
60├── project.json                   # Nx project configuration
61├── package.json                   # NPM package configuration
62├── tsconfig.json                  # TypeScript configuration
63└── jest.config.ts                 # Jest testing configuration
64```
65 
66### Key Components
67 
68**Core API Pattern**: The SDK follows a client-builder pattern with three main APIs:
69- `client.page.get()` - Fetches complete page content with layout and containers
70- `client.content.getCollection()` - Builder pattern for querying content collections
71- `client.navigation.get()` - Fetches site navigation structure
72 
73**Build Targets**:
74- `build` - Standard library build producing ESM/CJS dual packages
75- `build:js` - Specialized esbuild for editor integration (outputs to `dotCMS/src/main/webapp/html/js/editor-js`)
76 
77## Development Standards
78 
79### TypeScript Configuration
80- **Strict mode enabled**: Full TypeScript strict checking
81- **Target**: ES2020 with lib support for ES2020, DOM, DOM.Iterable
82- **Dual package support**: ESM and CJS through Rollup build
83- **Type definitions**: `@dotcms/types` for comprehensive type safety
84 
85### Code Patterns
86 
87#### Client Builder Pattern
88```typescript
89// Main client initialization
90const client = createDotCMSClient({
91    dotcmsUrl: 'https://instance.com',
92    authToken: 'token',
93    siteId: 'site-id'
94});
95 
96// Page API - single request for complete page
97const { pageAsset } = await client.page.get('/about-us');
98 
99// Content API - fluent builder pattern
100const blogs = await client.content
101    .getCollection('Blog')
102    .query((qb) => qb.field('title').equals('dotCMS*'))
103    .limit(10)
104    .sortBy([{ field: 'publishDate', direction: 'desc' }]);
105```
106 
107#### GraphQL Integration
108```typescript
109// Extend page requests with GraphQL for additional content
110const { pageAsset, content } = await client.page.get('/about-us', {
111    graphql: {
112        page: `title vanityUrl { url }`,
113        content: {
114            blogs: `BlogCollection(limit: 3) { title urlTitle }`,
115            navigation: `DotNavigation(uri: "/", depth: 2) { href title }`
116        }
117    }
118});
119```
120 
121#### Query Builder Pattern
122```typescript
123// Fluent query building for content collections
124const query = await client.content
125    .getCollection('Product')
126    .query((qb) => qb
127        .field('category').equals('electronics')
128        .and()
129        .field('price').raw(':[100 TO 500]')
130        .not()
131        .field('discontinued').equals('true')
132    )
133    .limit(10)
134    .page(1);
135```
136 
137### Testing Standards
138 
139#### Jest Configuration
140- **Framework**: Jest with TypeScript support
141- **Coverage**: Outputs to `../../../coverage/libs/sdk/client`
142- **File patterns**: `**/*.spec.ts` and `**/*.test.ts`
143- **CI mode**: Supports CI configuration with coverage reporting
144 
145#### Test Patterns
146```typescript
147// Use descriptive test names and group related tests
148describe('DotCMSClient', () => {
149    describe('page.get()', () => {
150        it('should fetch page content with default options', async () => {
151            // Test implementation
152        });
153        
154        it('should apply GraphQL extensions correctly', async () => {
155            // Test implementation
156        });
157    });
158});
159 
160// Mock external dependencies
161jest.mock('../utils/fetch', () => ({
162    dotFetch: jest.fn()
163}));
164```
165 
166### Build System Integration
167 
168#### Nx Monorepo Integration
169- **Executor**: `@nx/rollup:rollup` for main build, `@nx/esbuild:esbuild` for editor build
170- **Outputs**: Dual package (ESM/CJS) with proper export maps
171- **Dependencies**: Automatically managed through Nx dependency graph
172 
173#### Export Configuration
174```typescript
175// Package exports support both named and default imports
176export { createDotCMSClient } from './lib/client/client';
177export type { DotCMSClient } from './lib/client/client';
178 
179// Internal exports for framework SDKs
180export { DotCMSClientImpl } from './lib/client/client-impl';
181```
182 
183## Key Configuration Files
184 
185- **project.json**: Nx project configuration with build targets
186- **package.json**: NPM package metadata with proper exports field
187- **tsconfig.json**: TypeScript configuration with strict mode
188- **tsconfig.lib.json**: Library-specific TypeScript settings
189- **jest.config.ts**: Jest testing configuration
190 
191## Development Workflow
192 
193### Standard Development Flow
1941. **Make changes** → Test locally with `nx test sdk-client`
1952. **Lint code** → `nx lint sdk-client`
1963. **Build library** → `nx build sdk-client`
1974. **Integration testing** → Test with dependent SDKs or examples
198 
199### Editor Integration Build
200For changes affecting the editor integration:
2011. **Build editor version** → `nx run sdk-client:build:js`
2022. **Test in dotCMS editor** → Verify functionality in dotCMS admin
2033. **Clean build artifacts** → Script automatically removes temporary files
204 
205### Release Process
2061. **Version bump** → Update version in `package.json`
2072. **Build all targets** → `nx build sdk-client`
2083. **Publish** → `nx run sdk-client:publish --args.ver=X.X.X --args.tag=latest`
209 
210## Integration Context
211 
212### Framework SDKs
213This client SDK serves as the foundation for:
214- `@dotcms/react` - React integration with UVE support
215- `@dotcms/angular` - Angular integration with UVE support
216- `@dotcms/uve` - Universal Visual Editor low-level integration
217 
218### Dependencies
219- **Runtime**: `consola` for logging
220- **Development**: `@dotcms/types` for TypeScript definitions
221- **Peer Dependencies**: Framework-specific SDKs extend this client
222 
223## Common Development Tasks
224 
225### Adding New API Methods
2261. **Define interfaces** in `lib/client/models/`
2272. **Implement method** in appropriate API class (`page/`, `content/`, `navigation/`)
2283. **Export** from main `index.ts`
2294. **Add tests** following existing patterns
2305. **Update TypeScript types** if needed
231 
232### Extending Query Builders
2331. **Add method** to appropriate builder class
2342. **Update builder interface** with new method signature
2353. **Add tests** for new query capabilities
2364. **Document** in README with examples
237 
238### GraphQL Integration
2391. **Define GraphQL fragments** in `utils/graphql/`
2402. **Add to page API** GraphQL parameter types
2413. **Test** with various GraphQL queries
2424. **Update documentation** with new capabilities
243 
244## Summary Checklist
245- ✅ Use Nx commands for all build/test operations
246- ✅ Follow client-builder pattern for new APIs
247- ✅ Maintain TypeScript strict mode compliance
248- ✅ Write comprehensive Jest tests for new features
249- ✅ Use proper export patterns for dual package support
250- ✅ Test both ESM and CJS builds
251- ✅ Verify editor integration when making core changes
252- ❌ Avoid breaking changes to public API without migration plan
253- ❌ Don't add runtime dependencies without careful consideration