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## Essential Commands
6 
7### Development Commands
8```bash
9# Build the library
10nx build sdk-react
11 
12# Run tests
13nx test sdk-react
14 
15# Run tests with coverage
16nx test sdk-react --configuration=ci
17 
18# Lint code
19nx lint sdk-react
20 
21# Run specific test file
22nx test sdk-react --testNamePattern="DotCMSLayoutBody"
23```
24 
25### Package Management
26```bash
27# Install dependencies (run from workspace root)
28npm install
29 
30# Publish package (from dist directory)
31nx nx-release-publish sdk-react
32```
33 
34## Architecture Overview
35 
36This is the **@dotcms/react** SDK - a React component library that provides components and hooks for integrating React applications with dotCMS. The library is built using **Nx** as a monorepo tool with **Rollup** for bundling.
37 
38### Key Technologies
39- **React 18+** (peer dependency)
40- **TypeScript** with strict mode
41- **Nx** for build tooling and project management
42- **Rollup** for ESM bundling
43- **Jest** for testing
44- **ESLint** for linting
45- **Babel** for transformation
46 
47### Project Structure
48```
49src/
50├── index.ts                # Main export file
51└── lib/
52    └── next/               # Next.js optimized components
53        ├── components/     # React components
54        │   ├── DotCMSLayoutBody/
55        │   ├── DotCMSShow/
56        │   ├── DotCMSEditableText/
57        │   └── DotCMSBlockEditorRenderer/
58        ├── hooks/          # Custom React hooks
59        └── contexts/       # React contexts
60```
61 
62## Core Components & Patterns
63 
64### Component Architecture
65All components follow these patterns:
66 
671. **Client-side only components** - Use React hooks and contexts
682. **TypeScript interfaces** - Proper typing with `@dotcms/types`
693. **Modular CSS** - CSS modules where needed
704. **Comprehensive testing** - Jest with React Testing Library
71 
72### Key Dependencies
73- `@dotcms/uve`: Universal Visual Editor integration
74- `@dotcms/client`: Core dotCMS client functionality
75- `@dotcms/types`: TypeScript definitions
76- `@tinymce/tinymce-react`: Rich text editing
77 
78### Export Strategy
79The library uses a clean export pattern from `src/index.ts`:
80- All public components and hooks are explicitly exported
81- Components are exported with their prop types
82- Follows tree-shaking friendly patterns
83 
84## Development Workflow
85 
86### Testing Standards
87- **Jest** configuration in `jest.config.ts`
88- Tests located in `__test__/` directories
89- Test files follow pattern: `ComponentName.test.tsx`
90- Use React Testing Library for component testing
91- Mock external dependencies in `mock.ts`
92 
93### Building & Distribution
94- **Rollup** builds ESM modules for distribution
95- Output goes to `dist/libs/sdk/react/`
96- Package includes README.md as asset
97- Generates exports field automatically
98- External dependencies: `react/jsx-runtime`
99 
100### Code Quality
101- **ESLint** configuration for React/TypeScript
102- **Strict TypeScript** mode enabled
103- **Babel** transformation for Jest
104- **Coverage** reporting to workspace root
105 
106## Key Integration Points
107 
108### dotCMS Integration
109- Integrates with dotCMS Universal Visual Editor (UVE)
110- Uses `@dotcms/client` for API communication
111- Supports real-time page editing through UVE context
112- Handles dotCMS page asset rendering
113 
114### React Patterns
115- Uses React 18+ features (jsx-runtime)
116- Context-based state management
117- Custom hooks for dotCMS functionality
118- Supports both development and production modes
119 
120### Universal Visual Editor (UVE)
121- `useEditableDotCMSPage` hook for real-time editing
122- `DotCMSShow` component for conditional rendering
123- `DotCMSEditableText` for inline text editing
124- Mode detection (EDIT, PREVIEW, PUBLISHED)
125 
126## Important Notes
127 
128### Peer Dependencies
129- React 18+ and React DOM 18+ are required
130- No direct React dependencies to avoid version conflicts
131- Uses latest versions of internal dotCMS packages
132 
133### Build Configuration
134- Targets ESM format only
135- Uses Babel for Jest transformation
136- Rollup handles bundling with React plugins
137- CSS extraction is disabled (CSS-in-JS approach)
138 
139### Testing Environment
140- Jest preset from workspace root
141- React-specific transformations
142- Coverage directory in workspace root
143- Supports CI configuration with coverage reporting
144