[EPIC]: Universal Visual Editor and SDK Stable Release

[rjvelazco]

Overview

Transform the dotCMS Universal Visual Editor (UVE) and JavaScript SDK from alpha to a production-ready, stable release by addressing core architectural challenges, improving the developer experience, and ensuring reliable content-editing capabilities across frameworks.

Goals

1. Core Architecture

   • Implement unified content fetching through GraphQL and Navigation API
   • Create reliable UVE detection for both server and client environments
   • Establish stable communication between UVE and client applications
   • Resolve the preview mode/isInsideEditor functionality

2. Developer Experience

   • Eliminate redundant configuration requirements
   • Standardize component CSS classes and HTML structure
   • Improve error handling and debugging capabilities
   • Clean up SDK exports and provide clear public APIs

3. Content Management

   • Enable content editing anywhere on the page
   • Implement a reliable content subscription mechanism
   • Support complex data requirements through GraphQL
   • Handle both server-side and client-side data fetching

4. Framework Support

   • Ensure compatibility with core LTS versions
   • Provide framework-agnostic core libraries
   • Maintain backward compatibility where possible

Non-Goals:

• Real-time in-memory page state updates.
• Complex caching (handled by dotCMS CDN)
• Advanced performance optimizations.
• Establishing monitoring systems.

Requirements

Functional Requirements

1. SDK Enhancements

   • Support GraphQL queries for unified content fetching.
   • Enable real-time subscriptions to content updates.
   • Provide robust UVE detection for both client and server environments.

2. Three Pillars Integration

   • Content: Standardize content queries for flexibility in fetching.
   • Page: Support editable pages with full compatibility in UVE.
   • Navigation: Ensure reliable fetching and rendering of navigation data.

3. Framework Support

   • React hooks, Angular services, and Next.js utilities for seamless integration.
   • Maintain compatibility with LTS versions of frameworks.

4. Developer Experience

   • Simplify configuration and API usage.
   • Provide migration guides and examples to ease the transition from older SDKs.
   • Eliminate redundant or excessive HTML elements.

Non-Functional Requirements

• Optimize performance for high-traffic use cases with query batching.
• Ensure compatibility with existing dotCMS workflows.
• Conduct a thorough security audit of the SDK.

Phases and Milestones

Phase 1: Core Implementation

• Setup communication layer
• Implement GraphQL integration and query merging
• Establish UVE detection (server/client)
• Create React hooks and Angular solutions
• Standardize component structure and CSS

Phase 2: Framework Support

• Implement framework-specific integrations
• Ensure compatibility with LTS versions of React, Angular, and Next.js.
• Update documentation
• Develop migration guides

Phase 3: Testing & Release

• Comprehensive testing
• Performance optimization
• Security audit
• Beta and stable release

Acceptance Criteria

1. Core Functionality

• GraphQL integration supports query merging and subscriptions
• UVE detection works reliably in all environments
• Preview mode and isInsideEditor function correctly
• Content subscription provides consistent updates
• Navigation handles without redundant API calls
• Content editing works anywhere on the page

2. Developer Experience

• No manual parameter formatting is required
• Error boundaries prevent application crashes
• Standardized component CSS classes and HTML structure
• Clean SDK exports with clear public/private separation
• Comprehensive error messages and debugging information

3. Framework Support

• Working implementations for:
  • Next.js
  • Angular
  • Astro
• Example applications demonstrating:
  • Editable listing pages
  • Editable detail pages
  • Content editing outside layout
  • Navigation integration
  • GraphQL usage

4. Documentation & Testing

• Complete migration guide from alpha
• Framework-specific integration guides
• API documentation
• Test coverage >80%
• Security audit passed
• Performance benchmark documentation

5. Performance & Stability

• Zero subscription overhead in production
• SSR performance within acceptable limits
• No memory leaks in long-running sessions
• Stable under high concurrent edit load

Dependencies

• GraphQL API enhancements
• Framework compatibility requirements
• Security requirements for iframe sandbox

Risks

• Framework compatibility challenges
• Performance impact of real-time updates
• Migration complexity for existing implementations
• Security considerations for iframe communication

Resources

• Design Doc: Research and Improve dotCMS SDK & UVE Architecture

Proposed Objective

Core Features

Proposed Priority

Priority 2 - Important

Important

EACH CHANGE SHOULD BE DOCUMENTED IN THIS DOC TO HELP US DESIGN A MIGRATION GUIDE
UVE & SDK IMPROVEMENTS: MIGRATION DOC

Warning

BEFORE DEFINING ANYTHING IN THE PUBLIC API, PLEASE REVIEW THE NAMING CONVENTION RULES: SDK Rules and Recommendations."

SPIKES | Generic Tasks

Preview Give feedback

1. [SPIKE] SDK: Public API Naming Convention #31152
   0 of 4
   OKR : Core Features Priority : 3 Average QA : Not Needed Release : 25.01.28 Team : Scout Type : Task +6
2. [SPIKE] SDK: create a @dotcms/types package #31225
   0 of 4
   OKR : Technical User Experience Priority : 2 High QA : Not Needed Team : Scout Triage Type : New Functionality +6
3. SDK: Update WF Action to publish libraries to NPM under -beta.X and next tags #31277
   3 of 3
   Merged Note to QA OKR : Technical User Experience Priority : 2 High QA : Passed Internal Release : 25.02.12 Team : Scout Triage Type : Task +9
4. [SPIKE] UVE: Removes isClientReady and Redefining Initial Loading State Handling #31091
   0 of 5
   OKR : Core Features Priority : 3 Average Team : Scout Triage Type : Task +5
5. [SPIKE] UVE: Embedding Edit Mode Logic in Backend Response #31151
   0 of 6
   OKR : Core Features Priority : 3 Average Team : Scout Triage Type : Task +5
6. GraphQL: Add runningExperimentId in the Page Field #31251
   0 of 2
   OKR : Technical User Experience Priority : 3 Average Team : Scout Triage Type : Task +5
7. SDK: Define Public API in client SDK #31076
   0 of 5
   OKR : Core Features Priority : 2 High Team : Scout Triage Type : Task +5
8. SDK: Experiments lib is not building #31419
   Team : Scout Triage Type : Defect +3
   

Client SDK

Preview Give feedback

1. SDK: Add getUVEState() function #31090
   6 of 6
   Doc : Needs Doc Merged Note to QA OKR : Core Features Priority : 3 Average QA : Passed Internal Release : 25.02.12 Team : Scout Triage Type : Task +10
2. SDK: Update SDK Library and UVE search bar to Use "personaId" Key #28819
   4 of 4
   Note to QA OKR : Core Features OKR : Documentation Priority : 3 Average QA : Passed Internal Release : 25.02.18 Team : Lunik Team : Scout Type : Defect +9
3. SDK: Provide a client.getPage method to fetch page, content, nav using graphQL #30968
   Doc : Needs Doc Priority : 2 High Team : Scout Triage Type : Task +5
   
4. SDK: @dotcms/client SDK into Separate Client and UVE SDKs #31158
   0 of 5
   Doc : Needs Doc Needs discussion Priority : 2 High Team : Scout Triage Type : Task +6

React SDK

Preview Give feedback

1. SDK: Create DotCMSLayoutBody React Component to render page content #31178
   8 of 8
   Merged QA : Needs Internal Team : Scout Type : Task +4
   
2. SDK: Develop useDotCMS React Hook #31134
   0 of 6
   OKR : Technical User Experience Priority : 3 Average Team : Scout Triage Type : Task +5
3. SDK: Standardize React Component CSS Classes and HTML Structure #30955
   0 of 9
   OKR : Documentation OKR : Technical User Experience Priority : 3 Average Team : Scout Triage Type : Task +6
4. SDK: Remove client.editor.on from DotcmsLayout React component #31226
   0 of 2
   OKR : User Experience Priority : 3 Average Team : Scout Triage Type : Defect +5
5. SDK: Create DotCMSShowControl React Component #31267
   0 of 3
   Priority : 3 Average Team : Scout Triage Type : Task +4

Angular SDK

Preview Give feedback

1. [SPIKE] SDK: Missing feature in Angular #31176
   0 of 3
   Priority : 3 Average QA : Not Needed Team : Scout Triage Type : Task +5
2. SDK: Develop an DotCMSService Angular Service #31210
   0 of 7
   OKR : Technical User Experience Team : Scout Triage Type : Task +4
3. SDK: Standardize Angular Component CSS Classes and HTML Structure #30957
   0 of 9
   OKR : Documentation OKR : Technical User Experience Priority : 3 Average Team : Scout Triage Type : Task +6
4. SDK: Create DotCMSPageBody Angular Component to render page content #31209
   0 of 9
   Team : Scout Triage Type : Task +3
5. SDK: Remove client.editor.on from DotcmsLayout Angular component #31227
   0 of 2
   OKR : User Experience Priority : 3 Average Team : Scout Triage Type : Defect +5
6. SDK: Create dotCMSShowControl Angular directive #31268
   0 of 3
   Priority : 3 Average Team : Scout Triage Type : Task +4
7. SDK: Implement BlockEditorRenderer Component in Angular SDK #31368
   Team : Scout Triage Type : Task +3

UVE

Preview Give feedback

1. UVE: Request page using Graphql #30970
   0 of 4
   OKR : Technical User Experience Priority : 2 High Team : Scout Triage Type : Task +5
2. UVE: Remove loading state when page does not emit the CLIENT_IS_READY event #31219
   0 of 2
   OKR : User Experience Priority : 3 Average Team : Scout Triage Type : Task +5
3. UVE: Avoid Changing iframe URL in Headless Mode for Faster Content Updates #31139
   0 of 4
   OKR : Core Features Priority : 3 Average Team : Scout Triage Type : Task +5

Example SDK

Preview Give feedback

1. SDK Example: Adding Editable Listing Page Example to NextJS, Angular, and Astro Examples #30702
   0 of 4
   Team : Lunik Team : Scout Triage Type : Task +4
2. SDK Example: Adding Editable Detail Page Example to NextJS, Angular, and Astro Examples #30703
   0 of 4
   Team : Lunik Team : Scout Triage Type : Task +4
3. SDK Example: Implement editContentlet in Angular Example #31370
   Team : Scout Triage Type : Task +3
4. SDK Example: Implement Page Using GQL in Angular Example #31371
   Team : Scout Triage Type : Task +3
5. SDK Example: Fix siteId in Angular Example #31373
   Team : Scout Triage Type : Task +3
6. SDK: Improve All Examples Documentation #29560
   OKR : Technical User Experience Priority : 3 Average Team : Scout Triage Type : Task +5
7. SDK Examples: Enhance Image Management #30717
   OKR : User Experience Priority : 4 Low Team : Scout Triage Type : Defect +5
8. SDK Example: Implement ReorderMenu in Angular #31369
   Triage Type : Task +2