# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Essential Commands

### Development Commands
```bash
# Build the library
nx build sdk-react

# Run tests (Vitest)
pnpm nx test sdk-react

# Run a single test file
pnpm nx test sdk-react -- src/lib/next/__test__/components/Contentlet.test.tsx

# Lint code
pnpm nx lint sdk-react
```

### Package Management
```bash
# Install dependencies (run from core-web)
pnpm install

# Publish package (from dist directory)
nx nx-release-publish sdk-react
```

## Architecture Overview

This 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.

### Key Technologies
- **React 18+** (peer dependency)
- **TypeScript** with strict mode
- **Nx** for build tooling and project management
- **Rollup** for ESM bundling
- **Vitest** + Testing Library for testing
- **ESLint** for linting
- **Babel** for transformation

### Project Structure
```
src/
├── index.ts                # Main export file
└── lib/
    └── next/               # Next.js optimized components
        ├── components/     # React components
        │   ├── DotCMSLayoutBody/
        │   ├── DotCMSShow/
        │   ├── DotCMSEditableText/
        │   └── DotCMSBlockEditorRenderer/
        ├── hooks/          # Custom React hooks
        └── contexts/       # React contexts
```

## Core Components & Patterns

### Component Architecture
All components follow these patterns:

1. **Client-side only components** - Use React hooks and contexts
2. **TypeScript interfaces** - Proper typing with `@dotcms/types`
3. **Modular CSS** - CSS modules where needed
4. **Comprehensive testing** - Vitest with React Testing Library

### Key Dependencies
- `@dotcms/uve`: Universal Visual Editor integration
- `@dotcms/client`: Core dotCMS client functionality
- `@dotcms/types`: TypeScript definitions
- `@tinymce/tinymce-react`: Rich text editing

### Export Strategy
The library uses a clean export pattern from `src/index.ts`:
- All public components and hooks are explicitly exported
- Components are exported with their prop types
- Follows tree-shaking friendly patterns

## Development Workflow

### Testing Standards
- **Vitest**, configured in `vite.config.mts` — which is GENERATED by `core-web/tools/generate-vite-configs.mjs`. Regenerate it rather than hand-editing.
- Tests located in `__test__/` directories
- Test files follow pattern: `ComponentName.test.tsx`
- Use React Testing Library for component testing
- Mock external dependencies in `mock.ts`
- `DotCMSLayoutBody.runtime.test.tsx` guards the per-layout-tree work: one analytics listener for the whole tree, and no `getBoundingClientRect()` in production. Bundle-level guarantees (TinyMCE stays out of a layout import, sizes stay under budget) live in the separate `sdk-bundle-budgets` project, because they are properties of the built package rather than the source.

### Building & Distribution
- **Rollup** builds ESM modules for distribution, with `preserveModules` so consumers can tree-shake
- Output goes to `dist/libs/sdk/react/`
- Package includes README.md as asset
- `rollup.migrated.config.js` post-processes the build: it adds the `react-server` export condition, puts `types` first in the exports map, declares `sideEffects` as an allow-list (the CSS is injected by JS, so a blanket `false` would drop the grid styles), and replaces `@nx/rollup`'s postcss plugin, whose file filter does not match absolute module ids
- External dependencies: `react/jsx-runtime`

### Code Quality
- **ESLint** configuration for React/TypeScript
- **Strict TypeScript** mode enabled
- **Babel** transformation for the rollup build
- **Coverage** reporting to workspace root

## Key Integration Points

### dotCMS Integration
- Integrates with dotCMS Universal Visual Editor (UVE)
- Uses `@dotcms/client` for API communication
- Supports real-time page editing through UVE context
- Handles dotCMS page asset rendering

### React Patterns
- Uses React 18+ features (jsx-runtime)
- Context-based state management
- Custom hooks for dotCMS functionality
- Supports both development and production modes

### Universal Visual Editor (UVE)
- `useEditableDotCMSPage` hook for real-time editing
- `DotCMSShow` component for conditional rendering
- `DotCMSEditableText` for inline text editing — the TinyMCE integration is code-split into `TinyMCEEditor.tsx` and loaded with a dynamic import only once UVE enters edit mode. Do not import that module statically from anywhere else.
- Mode detection (EDIT, PREVIEW, PUBLISHED)

## Important Notes

### Peer Dependencies
- React 18+ and React DOM 18+ are required
- No direct React dependencies to avoid version conflicts
- `@dotcms/uve`, `@dotcms/client` and `@dotcms/types` are peers, each declared with the `"0.0.0"` sentinel — a slot marker the SDK release workflow overwrites with the exact release version at publish, never a version anyone installs. `@dotcms/types` belongs there despite its name: the built `.js` imports runtime enums (`UVE_MODE`, `UVEEventType`, `DotCMSUVEAction`, `DotCMSEntityState`) from it, so leaving it a devDependency ships a package that cannot import in a clean `node_modules`.

### Build Configuration
- Targets ESM format only
- Uses Babel for the rollup build
- Rollup handles bundling with React plugins
- CSS extraction is disabled (CSS-in-JS approach)

### Testing Environment
- Vitest config generated by `core-web/tools/generate-vite-configs.mjs`
- React-specific transformations
- Coverage directory in workspace root
- Supports CI configuration with coverage reporting