@dotcms/react 0.0.1-beta.33 → 0.0.1-beta.34

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +512 -160
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,259 +1,611 @@
1
- # @dotcms/react
1
+ # dotCMS React SDK
2
2
 
3
- `@dotcms/react` is the official set of React components and hooks designed to work seamlessly with dotCMS, making it easy to render dotCMS pages and use the page builder.
3
+ The `@dotcms/react` SDK is the DotCMS official React library. It empowers React developers to build powerful, editable websites and applications in no time.
4
4
 
5
- > **Note:** This SDK is currently in **beta** (v0.0.1-beta.13 or newest).
6
- >
7
- > For comprehensive documentation, visit our [developer portal](https://dev.dotcms.com/docs/javascript-sdk-react-library).
5
+ ## Table of Contents
8
6
 
9
- > **⚠️ IMPORTANT:** Versions published under the `next` tag (`npm install @dotcms/react@next`) are experimental, in beta, and not code complete. For the current stable and functional version, please use `latest` (`npm install @dotcms/react@latest`). Once we release the stable version, we will provide a migration guide from the alpha to stable version. The current alpha version (under `latest`) will continue to work, allowing you to migrate progressively at your own pace.
7
+ - [Prerequisites & Setup](#prerequisites--setup)
8
+ - [Get a dotCMS Environment](#get-a-dotcms-environment)
9
+ - [Create a dotCMS API Key](#create-a-dotcms-api-key)
10
+ - [Configure The Universal Visual Editor App](#configure-the-universal-visual-editor-app)
11
+ - [Installation](#installation)
12
+ - [dotCMS Client Configuration](#dotcms-client-configuration)
13
+ - [Proxy Configuration for Static Assets](#proxy-configuration-for-static-assets)
14
+ - [Quickstart: Render a Page with dotCMS](#quickstart-render-a-page-with-dotcms)
15
+ - [Example Project](#example-project-)
16
+ - [SDK Reference](#sdk-reference)
17
+ - [DotCMSLayoutBody](#dotcmslayoutbody)
18
+ - [DotCMSShow](#dotcmsshow)
19
+ - [DotCMSBlockEditorRenderer](#dotcmsblockeditorrenderer)
20
+ - [DotCMSEditableText](#dotcmseditabletext)
21
+ - [useEditableDotCMSPage](#useeditabledotcmspage)
22
+ - [useDotCMSShowWhen](#usedotcmsshowwhen)
23
+ - [Troubleshooting](#troubleshooting)
24
+ - [Common Issues & Solutions](#common-issues--solutions)
25
+ - [Debugging Tips](#debugging-tips)
26
+ - [Version Compatibility](#version-compatibility)
27
+ - [Still Having Issues?](#still-having-issues)
28
+ - [dotCMS Support](#dotcms-support)
29
+ - [How To Contribute](#how-to-contribute)
30
+ - [Licensing Information](#licensing-information)
10
31
 
11
- ## Table of Contents
32
+ ## Prerequisites & Setup
33
+
34
+ ### Get a dotCMS Environment
35
+
36
+ #### Version Compatibility
37
+
38
+ - **Recommended**: dotCMS Evergreen
39
+ - **Minimum**: dotCMS v25.05
40
+ - **Best Experience**: Latest Evergreen release
41
+
42
+ #### Environment Setup
43
+
44
+ **For Production Use:**
45
+
46
+ - ☁️ [Cloud hosting options](https://www.dotcms.com/pricing) - managed solutions with SLA
47
+ - 🛠️ [Self-hosted options](https://dev.dotcms.com/docs/current-releases) - deploy on your infrastructure
48
+
49
+ **For Testing & Development:**
50
+
51
+ - 🧑🏻‍💻 [dotCMS demo site](https://demo.dotcms.com/dotAdmin/#/public/login) - perfect for trying out the SDK
52
+ - 📘 [Learn how to use the demo site](https://dev.dotcms.com/docs/demo-site)
53
+ - 📝 Read-only access, ideal for building proof-of-concepts
54
+
55
+ **For Local Development:**
56
+
57
+ - 🐳 [Docker setup guide](https://github.com/dotCMS/core/tree/main/docker/docker-compose-examples/single-node-demo-site)
58
+ - 💻 [Local installation guide](https://dev.dotcms.com/docs/quick-start-guide)
59
+
60
+ ### Configure The Universal Visual Editor App
61
+
62
+ For a step-by-step guide on setting up the Universal Visual Editor, check out our [easy-to-follow instructions](https://dev.dotcms.com/docs/uve-headless-config) and get started in no time!
63
+
64
+ ### Create a dotCMS API Key
65
+
66
+ > [!TIP]
67
+ > Make sure your API Token has read-only permissions for Pages, Folders, Assets, and Content. Using a key with minimal permissions follows security best practices.
12
68
 
13
- - [What's New](#whats-new)
14
- - [What's Being Deprecated](#whats-being-deprecated)
15
- - [Installation](#installation)
16
- - [Dependencies](#dependencies)
17
- - [Browser Compatibility](#browser-compatibility)
18
- - [Components](#components)
19
- - [DotCMSLayoutBody](#dotcmslayoutbody)
20
- - [DotCMSShow](#dotcmsshow)
21
- - [BlockEditorRenderer](#blockeditorrenderer)
22
- - [Hooks](#hooks)
23
- - [useDotCMSShowWhen](#usedotcmsshowwhen)
24
- - [usePageAsset](#usepageasset)
25
- - [Making Your Page Editable](#making-your-page-editable)
26
- - [Contributing](#contributing)
27
- - [Licensing](#licensing)
28
- - [Support](#support)
29
- - [Documentation](#documentation)
30
-
31
- ## What's New?
32
-
33
- - **Refactored Components (v0.0.1-beta.13):** Improved structure for better maintainability and performance.
34
- - **New `DotCMSLayoutBody` Component (v0.0.1-beta.13):** Replaces `DotcmsLayout`, providing a more flexible approach to rendering page layouts.
35
- - **Enhanced Block Editor Support (v0.0.1-beta.13):** The `BlockEditorRenderer` now supports advanced custom renderers.
36
- - **Improved TypeScript Support (v0.0.1-beta.13):** Comprehensive typings for better developer experience.
37
-
38
- Install the latest version with:
69
+ This integration requires an API Key with read-only permissions for security best practices:
70
+
71
+ 1. Go to the **dotCMS admin panel**.
72
+ 2. Click on **System** > **Users**.
73
+ 3. Select the user you want to create the API Key for.
74
+ 4. Go to **API Access Key** and generate a new key.
75
+
76
+ For detailed instructions, please refer to the [dotCMS API Documentation - Read-only token](https://dev.dotcms.com/docs/rest-api-authentication#ReadOnlyToken).
77
+
78
+ ### Install Dependencies
39
79
 
40
80
  ```bash
41
- npm install @dotcms/react@0.0.1-beta.13
42
- # or use the newest version
43
- npm install @dotcms/react@latest
81
+ npm install @dotcms/react@next @dotcms/uve@next @dotcms/client@next @dotcms/types@next @tinymce/tinymce-react
44
82
  ```
45
83
 
46
- ## What's Being Deprecated?
84
+ ### dotCMS Client Configuration
47
85
 
48
- - **`DotcmsLayout` Component:** Now replaced by `DotCMSLayoutBody`.
49
- - **`useDotcmsPageContext` Hook:** No longer needed with the new component architecture.
50
- - **`Context Providers`:** These are being phased out in favor of a more direct approach.
86
+ ```typescript
87
+ import { createDotCMSClient } from '@dotcms/client';
51
88
 
52
- > **Note:** Deprecated items will continue to work and be supported, but won't receive new features or improvements. This approach allows users upgrading from alpha to beta or stable versions to update their codebase progressively without immediate breaking changes.
89
+ type DotCMSClient = ReturnType<typeof createDotCMSClient>;
53
90
 
54
- ## Installation
91
+ export const dotCMSClient: DotCMSClient = createDotCMSClient({
92
+ dotcmsUrl: 'https://your-dotcms-instance.com',
93
+ authToken: 'your-auth-token', // Optional for public content
94
+ siteId: 'your-site-id' // Optional site identifier/name
95
+ });
96
+ ```
55
97
 
56
- Install the package via npm:
98
+ ### Proxy Configuration for Static Assets
57
99
 
58
- ```bash
59
- npm install @dotcms/react
100
+ Configure a proxy to leverage the powerful dotCMS image API, allowing you to resize and serve optimized images efficiently. This enhances application performance and improves user experience, making it a strategic enhancement for your project.
101
+
102
+ #### 1. Configure Vite
103
+
104
+ ```ts
105
+ // vite.config.ts
106
+ import { defineConfig } from 'vite';
107
+ import dns from 'node:dns';
108
+
109
+ dns.setDefaultResultOrder('verbatim');
110
+
111
+ export default defineConfig({
112
+ server: {
113
+ proxy: {
114
+ '/dA': {
115
+ target: 'your-dotcms-instance.com',
116
+ changeOrigin: true
117
+ }
118
+ }
119
+ }
120
+ });
60
121
  ```
61
122
 
62
- Or using Yarn:
123
+ Learn more about Vite configuration [here](https://vitejs.dev/config/).
63
124
 
64
- ```bash
65
- yarn add @dotcms/react
125
+ #### 2. Usage in Components
126
+
127
+ Once configured, image URLs in your components will automatically be proxied to your dotCMS instance:
128
+
129
+ >📚 Learn more about [Image Resizing and Processing in dotCMS with React](https://www.dotcms.com/blog/image-resizing-and-processing-in-dotcms-with-angular-and-nextjs).
130
+
131
+ ```typescript
132
+ // /components/my-dotcms-image.tsx
133
+ import type { DotCMSBasicContentlet } from '@dotcms/types';
134
+
135
+ export const MyDotCMSImageComponent = ({ inode, title }: DotCMSBasicContentlet) => {
136
+ return <img src={`/dA/${inode}`} alt={title} />;
137
+ }
66
138
  ```
67
139
 
68
- ## Dependencies
140
+ ## Quickstart: Render a Page with dotCMS
69
141
 
70
- This package has the following peer dependencies that you'll need to install in your project:
142
+ The following example demonstrates how to quickly set up a basic dotCMS page renderer in your React application. This example shows how to:
71
143
 
72
- | Dependency | Version | Description |
73
- |------------|---------|-------------|
74
- | `@dotcms/uve` | * | Required for page editing functionality |
75
- | `react` | >=16.8.0 | React library |
76
- | `react-dom` | >=16.8.0 | React DOM library |
144
+ - Create a standalone component that renders a dotCMS page
145
+ - Set up dynamic component loading for different content types
146
+ - Handle both regular page viewing and editor mode
147
+ - Subscribe to real-time page updates when in the Universal Visual Editor
77
148
 
78
- Install peer dependencies:
149
+ ```tsx
150
+ // /src/app/pages/dotcms-page.tsx
151
+ import { useState, useEffect } from 'react';
152
+ import { DotCMSLayoutBody, useEditableDotCMSPage } from '@dotcms/react/next';
153
+ import { DotCMSPageResponse } from '@dotcms/types';
79
154
 
80
- ```bash
81
- npm install @dotcms/uve react react-dom
155
+ import { dotCMSClient } from './dotCMSClient';
156
+ import { BlogComponent } from './BlogComponent';
157
+ import { ProductComponent } from './ProductComponent';
158
+
159
+ const COMPONENTS_MAP = {
160
+ Blog: BlogComponent,
161
+ Product: ProductComponent
162
+ };
163
+
164
+ const MyPage = () => {
165
+ const [response, setResponse] = useState<DotCMSPageResponse | null>(null);
166
+ const { pageAsset } = useEditableDotCMSPage(response);
167
+
168
+ useEffect(() => {
169
+ dotCMSClient.page.get('/').then((response) => {
170
+ setResponse(response);
171
+ });
172
+ }, []);
173
+
174
+ return <DotCMSLayoutBody page={pageAsset} components={COMPONENTS_MAP} mode="development" />;
175
+ };
176
+
177
+ export default MyPage;
82
178
  ```
83
179
 
84
- ## Browser Compatibility
180
+ ### Example Project 🚀
85
181
 
86
- The @dotcms/react package is compatible with the following browsers:
182
+ Looking to get started quickly? We've got you covered! Our [Next.js starter project](https://github.com/dotCMS/core/tree/main/examples/nextjs) is the perfect launchpad for your dotCMS + Next.js journey. This production-ready template demonstrates everything you need:
87
183
 
88
- | Browser | Minimum Version | TLS Version |
89
- |---------|----------------|-------------|
90
- | Chrome | Latest 2 versions | TLS 1.2+ |
91
- | Edge | Latest 2 versions | TLS 1.2+ |
92
- | Firefox | Latest 2 versions | TLS 1.2+ |
184
+ 📦 Fetch and render dotCMS pages with best practices
185
+ 🧩 Register and manage components for different content types
186
+ 🔍 Listing pages with search functionality
187
+ 📝 Detail pages for blogs
188
+ 📈 Image and assets optimization for better performance
189
+ ✨ Enable seamless editing via the Universal Visual Editor (UVE)
190
+ ⚡️ Leverage React's hooks and state management for optimal performance
93
191
 
94
- ## Components
192
+ > [!TIP]
193
+ > This starter project is more than just an example, it follows all our best practices. We highly recommend using it as the base for your next dotCMS + Next.js project!
95
194
 
96
- ### `DotCMSLayoutBody`
195
+ ## SDK Reference
97
196
 
98
- The `DotCMSLayoutBody` component renders the layout body for a DotCMS page.
197
+ All components and hooks should be imported from `@dotcms/react/next`:
99
198
 
100
- #### Props
199
+ ### DotCMSLayoutBody
101
200
 
102
- | Prop | Type | Required | Description |
103
- |------|------|----------|-------------|
104
- | `page` | Object | Yes | The DotCMS page asset containing the layout information |
105
- | `components` | Object | Yes | A mapping of custom components for content rendering |
106
- | `mode` | String | No | The renderer mode; defaults to `'production'` |
201
+ `DotCMSLayoutBody` is a component used to render the layout for a DotCMS page, supporting both production and development modes.
202
+
203
+ | Input | Type | Required | Default | Description |
204
+ | ------------ | ------------------------ | -------- | -------------- | ---------------------------------------------- |
205
+ | `page` | `DotCMSPageAsset` | ✅ | - | The page asset containing the layout to render |
206
+ | `components` | `DotCMSPageComponent` | ✅ | `{}` | [Map of content type → React component](#component-mapping) |
207
+ | `mode` | `DotCMSPageRendererMode` | ❌ | `'production'` | [Rendering mode ('production' or 'development')](#layout-body-modes) |
208
+
209
+ #### Client-Side Only Component
210
+
211
+ > ⚠️ **Important: This is a client-side React component.**
212
+ > `DotCMSLayoutBody` uses React features like `useContext`, `useEffect`, and `useState`.
213
+ > If you're using a framework that supports Server-Side Rendering (like **Next.js**, **Gatsby**, or **Astro**), you **must** mark the parent component with `"use client"` or follow your framework’s guidelines for using client-side components.
214
+ >
215
+ > 👉 [Learn more: Next.js – Client Components](https://nextjs.org/docs/getting-started/react-essentials#client-components)
107
216
 
108
217
  #### Usage
109
218
 
110
- ```javascript
219
+ ```tsx
220
+ import type { DotCMSPageAsset } from '@dotcms/types';
111
221
  import { DotCMSLayoutBody } from '@dotcms/react/next';
112
222
 
113
- const MyPage = ({ page }) => {
114
- return <DotCMSLayoutBody page={page} components={components} />;
223
+ import { MyBlogCard } from './MyBlogCard';
224
+ import { DotCMSProductComponent } from './DotCMSProductComponent';
225
+
226
+ const COMPONENTS_MAP = {
227
+ Blog: MyBlogCard,
228
+ Product: DotCMSProductComponent
229
+ };
230
+
231
+ const MyPage = ({ pageAsset }: DotCMSPageResponse) => {
232
+ return <DotCMSLayoutBody page={pageAsset} components={COMPONENTS_MAP} />;
115
233
  };
116
234
  ```
117
235
 
118
- ### `DotCMSShow`
236
+ #### Layout Body Modes
119
237
 
120
- The `DotCMSShow` component conditionally renders content based on dotCMS conditions. It uses the UVE_MODE from `@dotcms/uve` which can be one of: `EDIT`, `PREVIEW`, or `LIVE`.
238
+ - `production`: Performance-optimized mode that only renders content with explicitly mapped components, leaving unmapped content empty.
239
+ - `development`: Debug-friendly mode that renders default components for unmapped content types and provides visual indicators and console logs for empty containers and missing mappings.
121
240
 
122
- #### Props
241
+ #### Component Mapping
123
242
 
124
- | Prop | Type | Required | Description |
125
- |------|------|----------|-------------|
126
- | `when` | String | Yes | The condition that determines if the content should be shown (EDIT, PREVIEW, LIVE) |
127
- | `children` | ReactNode | Yes | The content to be rendered when the condition is met |
243
+ The `DotCMSLayoutBody` component uses a `components` prop to map content type variable names to React components. This allows you to render different components for different content types. Example:
244
+
245
+ ```typescript
246
+ const DYNAMIC_COMPONENTS = {
247
+ Blog: MyBlogCard,
248
+ Product: DotCMSProductComponent
249
+ };
250
+ ```
251
+
252
+ - Keys (e.g., `Blog`, `Product`): Match your [content type variable names](https://dev.dotcms.com/docs/content-types#VariableNames) in dotCMS
253
+ - Values: Dynamic imports of your React components that render each content type
254
+ - Supports lazy loading through dynamic imports
255
+ - Components must be standalone or declared in a module
256
+
257
+ > [!TIP]
258
+ > Always use the exact content type variable name from dotCMS as the key. You can find this in the Content Types section of your dotCMS admin panel.
259
+
260
+
261
+ ### DotCMSEditableText
262
+
263
+ `DotCMSEditableText` is a component for inline editing of text fields in dotCMS, supporting plain text, text area, and WYSIWYG fields.
264
+
265
+ | Input | Type | Required | Description |
266
+ | ------------ | ------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
267
+ | `contentlet` | `T extends DotCMSBasicContentlet` | ✅ | The contentlet containing the editable field |
268
+ | `fieldName` | `keyof T` | ✅ | Name of the field to edit, which must be a valid key of the contentlet type `T` |
269
+ | `mode` | `'plain' \| 'full'` | ❌ | `plain` (default): Support text editing. Does not show style controls. <br/> `full`: Enables a bubble menu with style options. This mode only works with [`WYSIWYG` fields](https://dev.dotcms.com/docs/the-wysiwyg-field). |
270
+ | `format` | `'text' \| 'html'` | ❌ | `text` (default): Renders HTML tags as plain text <br/> `html`: Interprets and renders HTML markup |
128
271
 
129
272
  #### Usage
130
273
 
131
- ```javascript
274
+ ```tsx
275
+ import type { DotCMSBasicContentlet } from '@dotcms/types';
276
+ import { DotCMSEditableText } from '@dotcms/react/next';
277
+
278
+ const MyBannerComponent = ({ contentlet }: { contentlet: DotCMSBasicContentlet }) => {
279
+ const { inode, title, link } = contentlet;
280
+
281
+ return (
282
+ <div className="flex overflow-hidden relative justify-center items-center w-full h-96 bg-gray-200">
283
+ <img className="object-cover w-full" src={`/dA/${inode}`} alt={title} />
284
+ <div className="flex absolute inset-0 flex-col justify-center items-center p-4 text-center text-white">
285
+ <h2 className="mb-2 text-6xl font-bold text-shadow">
286
+ <DotCMSEditableText fieldName="title" contentlet={contentlet} />
287
+ </h2>
288
+ <a
289
+ href={link}
290
+ className="p-4 text-xl bg-red-400 rounded-sm transition duration-300 hover:bg-red-500">
291
+ See more
292
+ </a>
293
+ </div>
294
+ </div>
295
+ );
296
+ };
297
+
298
+ export default MyBannerComponent;
299
+ ```
300
+
301
+ #### Editor Integration
302
+
303
+ - Detects UVE edit mode and enables inline TinyMCE editing
304
+ - Triggers a `Save` [workflow action](https://dev.dotcms.com/docs/workflows) on blur without needing full content dialog.
305
+
306
+ #### DotCMSBlockEditorRenderer
307
+
308
+ `DotCMSBlockEditorRenderer` is a component for rendering [Block Editor](https://dev.dotcms.com/docs/block-editor) content from dotCMS with support for custom block renderers.
309
+
310
+ | Input | Type | Required | Description |
311
+ | ----------------- | -------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
312
+ | `blocks` | `BlockEditorContent` | ✅ | The [Block Editor](https://dev.dotcms.com/docs/block-editor) content to render |
313
+ | `customRenderers` | `CustomRenderers` | ❌ | Custom rendering functions for specific [block types](https://dev.dotcms.com/docs/block-editor#BlockTypes) |
314
+ | `className` | `string` | ❌ | CSS class to apply to the container |
315
+ | `style` | `CSSProperties` | ❌ | Inline styles for the container |
316
+
317
+ #### Usage
318
+
319
+ ```tsx
320
+ import type { DotCMSBasicContentlet } from '@dotcms/types';
321
+ import { DotCMSBlockEditorRenderer } from '@dotcms/react/next';
322
+
323
+ import { MyCustomBannerBlock } from './MyCustomBannerBlock';
324
+ import { MyCustomH1 } from './MyCustomH1';
325
+
326
+ const CUSTOM_RENDERERS = {
327
+ customBannerBlock: MyCustomBannerBlock,
328
+ h1: MyCustomH1
329
+ };
330
+
331
+ const DetailPage = ({ contentlet }: { contentlet: DotCMSBasicContentlet }) => {
332
+ return (
333
+ <DotCMSBlockEditorRenderer
334
+ blocks={contentlet['YOUR_BLOCK_EDITOR_FIELD']}
335
+ customRenderers={CUSTOM_RENDERERS}
336
+ />
337
+ );
338
+ };
339
+ ```
340
+
341
+ #### Recommendations
342
+
343
+ - Should not be used with [`DotCMSEditableText`](#dotcmseditabletext)
344
+ - Take into account the CSS cascade can affect the look and feel of your blocks.
345
+ - `DotCMSBlockEditorRenderer` only works with [Block Editor fields](https://dev.dotcms.com/docs/block-editor). For other fields, use [`DotCMSEditableText`](#dotcmseditabletext).
346
+
347
+ 📘 For advanced examples, customization options, and best practices, refer to the [DotCMSBlockEditorRenderer README](https://github.com/dotCMS/core/tree/master/core-web/libs/sdk/react/src/lib/components/DotCMSBlockEditorRenderer).
348
+
349
+ #### DotCMSShow
350
+
351
+ `DotCMSShow` is a component for conditionally rendering content based on the current UVE mode. Useful for mode-based behaviors outside of render logic.
352
+
353
+ | Input | Type | Required | Description |
354
+ | ---------- | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
355
+ | `children` | `ReactNode` | ✅ | Content to be conditionally rendered |
356
+ | `when` | `UVE_MODE` | ✅ | The `UVE` mode when content should be displayed: <br/> `UVE_MODE.EDIT`: Only visible in edit mode <br/> `UVE_MODE.PREVIEW`: Only visible in preview mode <br/> `UVE_MODE.PUBLISHED`: Only visible in published mode |
357
+
358
+ #### Usage
359
+
360
+ ```tsx
361
+ import { UVE_MODE } from '@dotcms/types';
132
362
  import { DotCMSShow } from '@dotcms/react/next';
133
- import { UVE_MODE } from '@dotcms/uve';
134
363
 
135
364
  const MyComponent = () => {
136
365
  return (
137
366
  <DotCMSShow when={UVE_MODE.EDIT}>
138
- <div>This content is only visible in edit mode</div>
367
+ <div>This will only render in UVE EDIT mode</div>
139
368
  </DotCMSShow>
140
369
  );
141
370
  };
142
371
  ```
143
372
 
144
- ### `BlockEditorRenderer`
373
+ 📚 Learn more about the `UVE_MODE` enum in the [dotCMS UVE Package Documentation](https://dev.dotcms.com/docs/uve).
145
374
 
146
- The `BlockEditorRenderer` component renders content from a Block Editor Content Type in dotCMS.
375
+ ### useEditableDotCMSPage
147
376
 
148
- #### Props
377
+ `useEditableDotCMSPage` is a hook that enables real-time page updates when using the Universal Visual Editor.
149
378
 
150
- | Prop | Type | Required | Description |
151
- |------|------|----------|-------------|
152
- | `blocks` | Block | Yes | The block editor content structure to render |
153
- | `customRenderers` | CustomRenderer | No | Optional custom renderers for specific block types |
154
- | `className` | String | No | Optional CSS class name to apply to the container |
155
- | `style` | React.CSSProperties | No | Optional inline styles to apply to the container |
156
- | `contentlet` | DotCMSContentlet | Only when editable is true | Contentlet object containing the field to be edited |
157
- | `fieldName` | String | Only when editable is true | Name of the field in the contentlet that contains the block editor content |
379
+ | Param | Type | Required | Description |
380
+ | -------------- | -------------------- | -------- | --------------------------------------------- |
381
+ | `pageResponse` | `DotCMSPageResponse` | ✅ | The page data object from `client.page.get()` |
158
382
 
159
- ## Hooks
383
+ #### Service Lifecycle & Operations
384
+
385
+ When you use the hook, it:
386
+
387
+ 1. Initializes the UVE with your page data
388
+ 2. Sets up communication channels with the editor
389
+ 3. Tracks content changes in real-time
390
+ 4. Updates your page automatically when:
391
+ - Content is edited inline
392
+ - Blocks are added or removed
393
+ - Layout changes are made
394
+ - Components are moved
395
+ 5. Cleans up all listeners and connections on destroy
396
+
397
+ #### Usage
398
+
399
+ ```tsx
400
+ 'use client';
401
+
402
+ import { useEditableDotCMSPage, DotCMSLayoutBody } from '@dotcms/react/next';
403
+ import type { DotCMSPageResponse } from '@dotcms/types';
404
+
405
+ const COMPONENTS_MAP = {
406
+ Blog: BlogComponent,
407
+ Product: ProductComponent
408
+ };
160
409
 
161
- ### `useDotCMSShowWhen`
410
+ export function DotCMSPage({ pageResponse }: { pageResponse: DotCMSPageResponse }) {
411
+ const { pageAsset } = useEditableDotCMSPage(pageResponse);
412
+ return <DotCMSLayoutBody pageAsset={pageAsset} components={COMPONENTS_MAP} />;
413
+ }
414
+ ```
162
415
 
163
- A custom hook that provides the same functionality as the `DotCMSShow` component in a hook form. It uses the UVE_MODE from `@dotcms/uve` which can be one of: `EDIT`, `PREVIEW`, or `LIVE`.
416
+ #### useDotCMSShowWhen
164
417
 
165
- #### Parameters
418
+ `useDotCMSShowWhen` is a hook for conditionally showing content based on the current UVE mode. Useful for mode-based behaviors outside of render logic.
166
419
 
167
- | Parameter | Type | Required | Description |
168
- |-----------|------|----------|-------------|
169
- | `mode` | String | Yes | The UVE mode to check against (EDIT, PREVIEW, LIVE) |
420
+ | Param | Type | Required | Description |
421
+ | ------ | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
422
+ | `when` | `UVE_MODE` | ✅ | The `UVE` mode when content should be displayed: <br/> `UVE_MODE.EDIT`: Only visible in edit mode <br/> `UVE_MODE.PREVIEW`: Only visible in preview mode <br/> `UVE_MODE.PUBLISHED`: Only visible in published mode |
170
423
 
171
424
  #### Usage
172
425
 
173
- ```javascript
426
+ ```tsx
427
+ import { UVE_MODE } from '@dotcms/types';
174
428
  import { useDotCMSShowWhen } from '@dotcms/react/next';
175
- import { UVE_MODE } from '@dotcms/uve';
176
429
 
177
- const MyComponent = () => {
178
- const isVisible = useDotCMSShowWhen(UVE_MODE.EDIT);
430
+ const MyEditButton = () => {
431
+ const isEditMode = useDotCMSShowWhen(UVE_MODE.EDIT); // returns a boolean
432
+
433
+ if (isEditMode) {
434
+ return <button>Edit</button>;
435
+ }
179
436
 
180
- return isVisible ? <div>Visible content</div> : null;
437
+ return null;
181
438
  };
182
439
  ```
183
440
 
184
- ### `usePageAsset`
441
+ ## Troubleshooting
185
442
 
186
- A custom hook that handles the communication with the Universal View Editor (UVE) and updates your page content in real-time when changes are made in the editor.
443
+ ### Common Issues & Solutions
187
444
 
188
- > **Note:** This hook will be built into the SDK in the stable version - the example below is a temporary workaround for the beta release.
189
- >
190
- > You need to save this hook in your project as a custom hook file.
445
+ #### Universal Visual Editor (UVE)
191
446
 
192
- #### Parameters
447
+ 1. **UVE Not Loading**: Page loads but UVE controls are not visible
448
+ - **Possible Causes**:
449
+ - Incorrect UVE configuration
450
+ - Missing API token permissions
451
+ - Missing the `DotCMSEditablePageService` call to enable UVE.
452
+ - **Solutions**:
453
+ - Verify UVE app configuration in dotCMS admin
454
+ - Check API token has edit permissions
455
+ - Ensure `dotcmsUrl` matches your instance URL exactly
193
456
 
194
- | Parameter | Type | Required | Description |
195
- |-----------|------|----------|-------------|
196
- | `currentPageAsset` | Object | Yes | The initial page asset from the server |
457
+ #### Missing Content
197
458
 
198
- #### Implementation
459
+ 1. **Components Not Rendering**: Empty spaces where content should appear
199
460
 
200
- ```typescript
201
- import { useEffect, useState } from 'react';
461
+ - **Possible Causes**:
462
+ - Missing component mappings
463
+ - Incorrect content type variable names
464
+ - **Solutions**:
465
+ - Check component registration in `components` prop
466
+ - Verify content type variable names match exactly
467
+ - Enable `development` mode for detailed logging
202
468
 
203
- import { getUVEState, sendMessageToEditor, createUVESubscription} from '@dotcms/uve';
204
- import { DotCMSUVEAction, UVEEventType} from '@dotcms/types';
469
+ 2. **Asset Loading Issues**: Images or files not loading
470
+ - **Possible Causes**:
471
+ - Proxy configuration issues
472
+ - CORS restrictions
473
+ - **Solutions**:
474
+ - Verify proxy settings in `vite.config.ts`
475
+ - Check network tab for CORS errors
476
+ - Ensure `/dA` path is properly configured
205
477
 
206
- export const usePageAsset = (currentPageAsset) => {
207
- const [pageAsset, setPageAsset] = useState(null);
208
- useEffect(() => {
209
- if (!getUVEState()) {
210
- return;
211
- }
478
+ #### Development Setup
212
479
 
213
- // Note: If using plain JavaScript instead of TypeScript, you can use the string literals directly
214
- sendMessageToEditor({ action: DotCMSUVEAction.CLIENT_READY || "client-ready" });
215
- const subscription = createUVESubscription(UVEEventType.CONTENT_CHANGES || "changes", (pageAsset) => setPageAsset(pageAsset));
480
+ 1. **Build Errors**: `npm install` fails
216
481
 
217
- return () => {
218
- subscription.unsubscribe();
219
- };
220
- }, [currentPageAsset]);
482
+ - **Solutions**:
483
+ - Clear npm cache: `npm cache clean --force`
484
+ - Delete `node_modules` and reinstall
485
+ - Verify Node.js version compatibility
221
486
 
222
- return pageAsset ?? currentPageAsset;
223
- };
224
- ```
487
+ 2. **Runtime Errors**: Console errors about missing imports or components not rendering
488
+ - **Solutions**:
489
+ - Check all imports are from `@dotcms/react/next`
490
+ - Verify all peer dependencies are installed
491
+ - Update to latest compatible versions
225
492
 
226
- #### Usage
493
+ #### Next.js App Router Integration
227
494
 
228
- ```typescript
229
- // Import the hook from where you saved it in your project
230
- import { usePageAsset } from './hooks/usePageAsset';
495
+ 1. **Server Component Errors**: Errors about React class components in Server Components
231
496
 
232
- const MyPage = ({ initialPageAsset }) => {
233
- const pageAsset = usePageAsset(initialPageAsset);
497
+ - **Possible Causes**:
498
+ - Using dotCMS components directly in Server Components
499
+ - Missing 'use client' directive
500
+ - Incorrect data fetching pattern
501
+ - **Solutions**:
234
502
 
235
- return <DotCMSLayoutBody page={pageAsset} components={components} />;
236
- };
237
- ```
503
+ 1. Split your code into Server and Client Components:
504
+
505
+ ```tsx
506
+ // app/page.tsx (Server Component)
507
+ import { DotCMSPage } from '@/components/DotCMSPage';
508
+ import { dotCMSClient } from '@/lib/dotCMSClient';
509
+
510
+ export default async function Page() {
511
+ const pageResponse = await dotCMSClient.page.get('/index');
512
+ return <DotCMSPage pageResponse={pageResponse} />;
513
+ }
514
+ ```
515
+
516
+ ```tsx
517
+ // components/DotCMSPage.tsx (Client Component)
518
+ 'use client';
519
+
520
+ import { useEditableDotCMSPage, DotCMSLayoutBody } from '@dotcms/react/next';
521
+ import type { DotCMSPageResponse } from '@dotcms/types';
522
+
523
+ const COMPONENTS_MAP = {
524
+ Blog: BlogComponent,
525
+ Product: ProductComponent
526
+ };
527
+
528
+ export function DotCMSPage({ pageResponse }: { pageResponse: DotCMSPageResponse }) {
529
+ const { pageAsset } = useEditableDotCMSPage(pageResponse);
530
+ return <DotCMSLayoutBody pageAsset={pageAsset} components={COMPONENTS_MAP} />;
531
+ }
532
+ ```
533
+
534
+ 2. Always fetch data in Server Components for better performance
535
+ 3. Use Client Components only for rendering dotCMS interactive components
536
+
537
+ ### Debugging Tips
538
+
539
+ 1. **Enable Development Mode**
540
+
541
+ ```typescript
542
+ <dotcms-layout-body
543
+ [page]="pageAsset()"
544
+ [components]="components()"
545
+ mode="development"
546
+ />
547
+ ```
548
+
549
+ This will:
550
+
551
+ - Show detailed error messages
552
+ - Highlight unmapped components
553
+ - Log component lifecycle events
554
+
555
+ 2. **Check Browser Console**
556
+
557
+ - Check for errors in the browser console
558
+ - Check for errors in the browser network tab
559
+
560
+ 3. **Network Monitoring**
561
+ - Use browser dev tools to monitor API calls
562
+ - Check for 401/403 errors (auth issues)
563
+ - Verify asset loading paths
564
+
565
+ ### Still Having Issues?
566
+
567
+ If you're still experiencing problems after trying these solutions:
568
+
569
+ 1. Search existing [GitHub issues](https://github.com/dotCMS/core/issues)
570
+ 2. Ask questions on the [community forum](https://community.dotcms.com/) to engage with other users.
571
+ 3. Create a new issue with:
572
+ - Detailed reproduction steps
573
+ - Environment information
574
+ - Error messages
575
+ - Code samples
576
+
577
+ ## dotCMS Support
578
+
579
+ We offer multiple channels to get help with the dotCMS React SDK:
238
580
 
239
- ## Making Your Page Editable
581
+ - **GitHub Issues**: For bug reports and feature requests, please [open an issue](https://github.com/dotCMS/core/issues/new/choose) in the GitHub repository.
582
+ - **Community Forum**: Join our [community discussions](https://community.dotcms.com/) to ask questions and share solutions.
583
+ - **Stack Overflow**: Use the tag `dotcms-react` when posting questions.
584
+ - **Enterprise Support**: Enterprise customers can access premium support through the [dotCMS Support Portal](https://helpdesk.dotcms.com/support/).
240
585
 
241
- To make your page editable in dotCMS, you need to use the `usePageAsset` hook described above. This hook synchronizes your page with the Universal View Editor (UVE) and ensures that any changes made in the editor are reflected in your React application in real-time.
586
+ When reporting issues, please include:
242
587
 
243
- You need to save the hook implementation in your project (for example, in a file like `hooks/usePageAsset.js`) and import it where needed.
588
+ - SDK version you're using
589
+ - React version
590
+ - Minimal reproduction steps
591
+ - Expected vs. actual behavior
244
592
 
245
- ## Contributing
593
+ ## How To Contribute
246
594
 
247
- GitHub pull requests are the preferred method to contribute code to dotCMS. Before any pull requests can be accepted, an automated tool will ask you to agree to the [dotCMS Contributor's Agreement](https://gist.github.com/wezell/85ef45298c48494b90d92755b583acb3).
595
+ GitHub pull requests are the preferred method to contribute code to dotCMS. We welcome contributions to the DotCMS UVE SDK! If you'd like to contribute, please follow these steps:
248
596
 
249
- ## Licensing
597
+ 1. Fork the repository [dotCMS/core](https://github.com/dotCMS/core)
598
+ 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
599
+ 3. Commit your changes (`git commit -m 'Add some amazing feature'`)
600
+ 4. Push to the branch (`git push origin feature/amazing-feature`)
601
+ 5. Open a Pull Request
250
602
 
251
- dotCMS comes in multiple editions and as such is dual licensed. The dotCMS Community Edition is licensed under the GPL 3.0 and is freely available for download, customization and deployment for use within organizations of all stripes. dotCMS Enterprise Editions (EE) adds a number of enterprise features and is available via a supported, indemnified commercial license from dotCMS. For the differences between the editions, see [the feature page](http://dotcms.com/cms-platform/features).
603
+ Please ensure your code follows the existing style and includes appropriate tests.
252
604
 
253
- ## Support
605
+ ## Licensing Information
254
606
 
255
- If you need help or have any questions, please [open an issue](https://github.com/dotCMS/core/issues/new/choose) in the GitHub repository.
607
+ dotCMS comes in multiple editions and as such is dual-licensed. The dotCMS Community Edition is licensed under the GPL 3.0 and is freely available for download, customization, and deployment for use within organizations of all stripes. dotCMS Enterprise Editions (EE) adds several enterprise features and is available via a supported, indemnified commercial license from dotCMS. For the differences between the editions, see [the feature page](http://www.dotcms.com/cms-platform/features).
256
608
 
257
- ## Documentation
609
+ This SDK is part of dotCMS's dual-licensed platform (GPL 3.0 for Community, commercial license for Enterprise).
258
610
 
259
- Always refer to the official [DotCMS documentation](https://www.dotcms.com/docs/latest/) for comprehensive guides and API references. For specific React library documentation, visit our [developer portal](https://dev.dotcms.com/docs/javascript-sdk-react-library).
611
+ [Learn more ](https://www.dotcms.com)at [dotcms.com](https://www.dotcms.com).
package/package.json CHANGED
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "@dotcms/react",
3
- "version": "0.0.1-beta.33",
3
+ "version": "0.0.1-beta.34",
4
4
  "peerDependencies": {
5
5
  "react": ">=18",
6
6
  "react-dom": ">=18",
7
- "@dotcms/client": "0.0.1-beta.33",
8
- "@dotcms/uve": "0.0.1-beta.33",
7
+ "@dotcms/client": "0.0.1-beta.34",
8
+ "@dotcms/uve": "0.0.1-beta.34",
9
9
  "@tinymce/tinymce-react": "^6.0.0"
10
10
  },
11
11
  "devDependencies": {