[SPIKE] SDK: Public API Naming Convention

[rjvelazco]

Important

Time Frame: 4-5 hours

Parent Issue

#30943

Overview

There is a need to review and normalize the naming convention used for the public API across these SDKs to ensure consistency, maintainability, and clarity for developers working with the SDKs.

Task

Define a standard for naming variables, classes, and functions exported to the client.

Define/Answer this questions

Preview Give feedback

1. Define The naming convention for the public API.
2. The new naming convention is documented in detail with examples.
3. What is the correct prefix for the public API (constants, functions, variables, classes) to use—dot or dotcms?
4. Should we use DotCms as the prefix for classes and main components, and dot for everything else?

DotCmsor Dotcms

In the @dotcms/client package, we use the naming convention DotCmsClient, while in the @dotcms/react package, we use DotcmsLayout. Which naming convention is correct—uppercase "C" or lowercase "c"? What is the industry standard for naming conventions in such cases? Is it suitable for us to use PascalCase?

Scope

• SDKs to Review: @dotcms/client, @dotcms/react, @dotcms/angular, and @dotcms/experiments
• Check out the SDK standard naming in the Industry.

Proposed Objective

Core Features

Proposed Priority

Priority 3 - Average

Important

What we're aiming for here is to standardize our public API to make it more readable, memorable, and closely aligned with dotCMS branding. In this case, using the dot prefix could be a suitable choice.
However, this ticket is about conducting some research on SDK standards, adapting them to meet our specific requirements, and then proposing our approach to other developers for feedback.

Assumptions & Considerations

• Consistency: Ensure naming consistency across all SDKs, with the same patterns used for similar entities across different frameworks.
• Developer Experience: Prioritize clarity and simplicity in naming to make the SDKs intuitive for developers.
• Compatibility: Ensure that the naming convention works well across the different environments (React, Angular, and others), and ensure it is easy for future developers to adopt.
• Backward Compatibility: If the changes are breaking, provide migration guides and consider how versioning will be handled.

[rjvelazco]

Note:

What we're aiming for here is to standardize our public API to make it more readable, memorable, and closely aligned with dotCMS branding. In this case, using the dot prefix could be a suitable choice.

However, this ticket isn't simply about renaming the Public API. We need to conduct some research on SDK standards, adapt them to meet our specific requirements, and then propose our approach to other developers for feedback.

[KevinDavilaDotCMS]

Findings

The Prefix in SDK Components

The standard requires a prefix for components exposed in the library, giving us the flexibility to handle internal components however we choose.
For example, in the React SDK, the exposed component is DotcmsLayout, while internal components are named Row, Column, and Container.

In the Angular SDK, the exposed component is <dotcms-layout />, and internal components include <dotcms-row>, <dotcms-column>, <dotcms-container>, and <dotcms-contentlet-wrapper>. This case is unique because folder and class names do not use the prefix, but the selectors (HTML tags) do.

A nice-to-have improvement would be to standardize internal components to use the prefix consistently.

In some components we use the prefix dot and in others dotCms

• Angular
  • dot-editable-text
  • dotcms-no-component
  • dotcms-contentlet-wrapper
  • DOTCMS_CLIENT_TOKEN
• Experiments
  • Inside we have DotExperimentsProvicer, DotExperimentHandlingComponent

The recommendation is to use the same prefix as the prefix across all components. While this is ultimately a team decision, I personally believe "DotCms" is the better choice as it directly reflects the company's brand.

In most internal interfaces, we currently use prefixes like Dot, DotCMS, or Dotcms.

As with components, we need to establish a standard and consistently apply it to all interfaces, types, enums, etc., across the SDKs.

• Angular:
  • DotCMSPageAsset
  • DotCMSContainer
  • DotPageAssetLayoutRow
  • DotcmsNavigationItem

This is a team decision. The community's recommendation is to use self-descriptive names and avoid prefixes whenever possible.

Names like PageAsset, Contentlet, Row, and Column are self-explanatory, but some, like Row, Column, and Container, can be too generic. To address this, we could consider using a prefix to make them more specific.

Exported Functions

We don’t use a prefix for exported functions, which aligns with best practices.
We could consider improving the naming of some functions by including actionable verbs.

postMessageToEditor => sendPostMessageToEditor

Client Initialization in Other Industry SDKs

Some industry SDKs provide functions to create their clients. Currently, we do the following:

const client = DotCms.init({})

However, we could create a function that abstracts this process, making it seamless for the user. This way, if we change the implementation in the future, it won’t impact the user.

const client = createClient({})

//...
function createClient(config) {
	return DotCms.init(config);
}

Exporting Unnecessary Items

Currently, we’re exporting things that aren’t relevant to the end user.

• Angular
  • DotCMSPageContext (Interface)
  • DotCMSSiteParentPermissionable (Interface)
  • DotPageAssetLayoutColumn (Interface)
  • etc
• React
  • Row
  • PageProvider
  • useDotcmsPageContext
• Client
  • CLIENT_ACTIONS: Used to send the Client ready. Unnecessary when the hook exists inside the sdk.
  • INLINE_EDITING.EVENT_KEY: 'BLOCK_EDITOR' | 'WYSIWYG'. Unused in the examples.
  • InlineEditEventData: Unused in the examples.
  • InlineEditorData: Unused in the examples.
  • NOTIFY_CLIENT: Actions sents from the editor. Unused in the examples.
  • UVE_MODE: 'edit' | 'preview'. Unused in the examples.
  • destroyEditoy: Unused in the examples.
  • initEditor: Unused in the examples.
  • initInlineEditing: Unused in the examples.

In my opinion, we should separate these as follows:

//Client SDK
"@dotcms/client" => Everything the developer needs to use the library in his project. ClientConfig, DotCMSClient, EditorConfig , etc( Some of this may change with the improvements in the SDK that we will make.)

//Angular 
"@dotcms/angular" => Everything the developer needs to use the library in his project. Includes<dotcms-layout> y las interfaces DotcmsNavigationItem, DotCMSPageAsset. The rest of things do not need to be exposed.

//React
"@dotcms/react" => DotcmsLayout, DotcmsNavigationItem, DotCMSPageAsset, BlockEditor Interfaces, The rest of things do not need to be exposed.

//Experiments
This only exports withExperiments, which is correct.

For this, I made this PoC to split our SDK.
Here is a short video explaining it.

poc-divide-index.mov

[KevinDavilaDotCMS]

@fmontes I think the prefix decision is a product decision, so it would be very helpful to read your opinion
For now we have the proposal:
Prefix: DotCms. Use it in Components, Interfaces, Classes, Types, etc. Functions and utilities will not have a prefix, they must have a self-explanatory name.
The prefix must be in all components, including those that are not exported

cc: @rjvelazco @zJaaal

[KevinDavilaDotCMS]

Final Decisions on Naming Conventions

After discussing with the team, these are the final decisions:

We will use the prefix DotCMS, following camel case conventions and web standards for uppercase and acronyms (e.g., URL, SVGCircleElement, etc.).

All classes, interfaces, types, and enums will have the prefix DotCMS.

Example: DotCMSPageAsset, DotCMSNavigationAsset.

All components (both internal and external) will also have the prefix DotCMS.

Example: DotCMSMenu, DotCMSCard.

Functions and utilities will NOT have the prefix. Instead, they should follow action-based, descriptive names:

Example: reorderMenu, editContentlet.

This naming convention will apply to all new development in the SDK, and we will progressively migrate existing code to align with this new standard.

This is explained in more detail in the DotCMS Frontend Best Practices Guide.

[rjvelazco]

Document resulting from this research: SDK Rules and recommendations