dotCMS Types Library

The @dotcms/types package contains TypeScript type definitions for the dotCMS ecosystem. Use it to enable type safety and an enhanced developer experience when working with dotCMS APIs and structured content.

📦 @dotcms/types on npm 🛠️ View source on GitHub

Table of Contents

• Overview
• Installation
• Which SDK Version Should I Use?
• Commonly Used Types
• Type Hierarchy (Jump to Definitions)
  • AI Search
  • dotCMS Content & Pages
  • Universal Visual Editor (UVE)
  • Block Editor
  • Client & HTTP
  • Error Handling
• Usage Examples
  • Error Type Checking
• Support
• Contributing
• Licensing
• Changelog

Overview

When to Use It

• Building TypeScript applications with dotCMS
• Enabling type safety in your dotCMS integrations
• Getting better IDE autocomplete and error checking
• Working with dotCMS Client SDK or other SDK packages

Key Benefits

• Type Safety: Catch errors at compile time instead of runtime
• IDE Support: Rich autocomplete and inline documentation
• Better Developer Experience: Clear interfaces for all dotCMS data structures
• Framework Agnostic: Works with any TypeScript project

Installation

npm install @dotcms/types@latest --save-dev

Which SDK Version Should I Use?

dotCMS SDKs are published in lockstep with dotCMS itself: every @dotcms/* package ships at the exact same version number as the dotCMS release it was built for (e.g. dotCMS 26.7.14-1 → @dotcms/[email protected], @dotcms/[email protected], and so on).

Simple rule of thumb: use the SDK version that matches your dotCMS instance's version.

You don't have to upgrade the SDK every time dotCMS releases a new version (or vice versa). Most releases don't change anything the SDKs rely on, so an older SDK usually keeps working fine against a newer dotCMS instance. Occasionally, though, a release does include a real breaking change — and if your SDK is older than that point, it will stop working correctly.

You don't need to track this yourself: your dotCMS instance always knows the oldest SDK version it still supports, and the SDK checks itself against it automatically. If you're using an SDK that's too old, you'll see a clear warning in your console telling you to upgrade.

Recommendation: pin your SDKs to the same version as your dotCMS instance, and only bump them when you upgrade dotCMS — or when the console tells you to.

On an LTS release? LTS releases don't currently get their own matching SDK version. Until that's addressed, use the SDK version published for the closest regular release at or before your LTS version.

Want more background on how dotCMS releases and support windows work? See Release & Support Lifecycle.

Commonly Used Types

import {
  DotCMSPageAsset,
  DotCMSPageResponse,
  UVEEventType,
  DotCMSInlineEditingPayload,
  DotHttpClient,
  DotHttpError,
  DotErrorPage,
  DotErrorContent,
  DotErrorNavigation,
  DotErrorAISearch,
  DotCMSAISearchParams,
  DISTANCE_FUNCTIONS
} from '@dotcms/types';

Type Hierarchy (Jump to Definitions)

AI Search

⚠️ Experimental: The AI Search types are experimental and may undergo breaking changes in future releases.

AI Search Parameters:

| Type | Description | |------|-------------| | DotCMSAISearchParams | Complete AI search parameters including query and AI config | | DotCMSAISearchQuery | Query parameters (limit, offset, contentType, etc.) | | DotCMSAIConfig | AI configuration (threshold, distanceFunction, responseLength) | | DISTANCE_FUNCTIONS | Available distance functions for vector similarity |

AI Search Response:

| Type | Description | |------|-------------| | DotCMSAISearchResponse | AI search API response structure | | DotCMSAISearchContentletData | Contentlet with AI match information | | DotCMSAISearchMatch | Individual match with distance score and extracted text |

AI Search Errors:

| Type | Description | |------|-------------| | DotErrorAISearch | AI Search API specific error with prompt, indexName and params context |

dotCMS Content & Pages

Page:

| Type | Description | |------|-------------| | DotCMSPageAsset | Complete page with layout and content | | DotCMSPage | Core page data | | DotCMSPageResponse | API response for page requests | | DotGraphQLApiResponse | GraphQL API response structure |

Content:

| Type | Description | |------|-------------| | DotCMSBasicContentlet | Basic contentlet structure |

Site & Layout:

| Type | Description | |------|-------------| | DotCMSSite | Site information | | DotCMSTemplate | Page templates | | DotCMSLayout | Page layout structure | | DotCMSPageAssetContainer | Container definitions |

Navigation:

| Type | Description | |------|-------------| | DotCMSNavigationItem | Navigation structure item with hierarchy support | | DotCMSVanityUrl | URL rewrites and vanity URLs | | DotCMSURLContentMap | URL to content mapping |

Universal Visual Editor (UVE)

Editor State:

| Type | Description | |------|-------------| | UVEState | Current editor state | | UVE_MODE | Editor modes (EDIT, PREVIEW, PUBLISHED) | | DotCMSPageRendererMode | Page rendering modes |

Editor Events:

| Type | Description | |------|-------------| | UVEEventHandler | Event handler functions | | UVEEventSubscriber | Event subscription management | | UVEEventType | Available event types | | UVEEventPayloadMap | Event payload definitions |

Inline Editing:

| Type | Description | |------|-------------| | DotCMSInlineEditingPayload | Inline editing data | | DotCMSInlineEditingType | Types of inline editing |

Block Editor

| Type | Description | |------|-------------| | BlockEditorContent | Block editor content structure | | BlockEditorNode | Individual blocks/nodes | | BlockEditorMark | Text formatting marks |

Client & HTTP

HTTP Client:

| Type | Description | |------|-------------| | DotHttpClient | HTTP client interface for custom implementations | | BaseHttpClient | Abstract base class with error handling utilities |

Client Configuration:

| Type | Description | |------|-------------| | DotCMSClientConfig | Client configuration options | | DotRequestOptions | HTTP request options | | DotCMSPageRequestParams | Page request parameters | | DotCMSGraphQLParams | GraphQL query parameters | | DotCMSNavigationRequestParams | Navigation request options |

Error Handling

Base Error Types:

| Type | Description | |------|-------------| | HttpErrorDetails | HTTP error details interface | | DotHttpError | Standardized HTTP error class |

Domain-Specific Errors:

| Type | Description | |------|-------------| | DotErrorPage | Page API errors with GraphQL context | | DotErrorContent | Content API specific error handling | | DotErrorNavigation | Navigation API error handling | | DotErrorAISearch | AI Search API error handling with prompt and params |

Usage Examples

Error Type Checking

import {
  DotHttpError,
  DotErrorPage,
  DotErrorContent,
  DotErrorNavigation,
  DotErrorAISearch
} from '@dotcms/types';

// Type-safe error handling
if (error instanceof DotHttpError) {
  // Access standardized HTTP error properties
  console.error(`HTTP ${error.status}: ${error.statusText}`);
  console.error('Response data:', error.data);
}

if (error instanceof DotErrorPage) {
  // Page-specific error with GraphQL context
  console.error('GraphQL query:', error.graphql?.query);
}

if (error instanceof DotErrorContent) {
  // Content-specific error context
  console.error(`${error.operation} failed for ${error.contentType}`);
}

if (error instanceof DotErrorAISearch) {
  // AI Search-specific error context
  console.error('AI Search failed for prompt:', error.prompt);
  console.error('Index name:', error.indexName);
  console.error('Search params:', error.params);
}

Note: For complete implementation examples and usage patterns, see the @dotcms/client package documentation.

Support

We offer multiple channels to get help with the dotCMS Types library:

• GitHub Issues: For bug reports and feature requests, please open an issue in the GitHub repository
• Community Forum: Join our community discussions to ask questions and share solutions
• Stack Overflow: Use the tag dotcms-types when posting questions
• Enterprise Support: Enterprise customers can access premium support through the dotCMS Support Portal

When reporting issues, please include:

• Package version you're using
• TypeScript version
• Minimal reproduction steps
• Expected vs. actual behavior

Contributing

GitHub pull requests are the preferred method to contribute code to dotCMS. We welcome contributions to the dotCMS Types library! If you'd like to contribute, please follow these steps:

1. Fork the repository dotCMS/core
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure your code follows the existing style and includes appropriate tests.

Changelog

[1.3.0]

✨ Added - AI Search Types (Experimental)

⚠️ Experimental: AI Search types are experimental and may undergo breaking changes in future releases.

New AI Search Types:

• DotCMSAISearchParams - Complete AI search parameters including query and AI config
• DotCMSAISearchQuery - Query parameters (limit, offset, contentType, etc.)
• DotCMSAIConfig - AI configuration (threshold, distanceFunction, responseLength)
• DotCMSAISearchResponse<T> - AI search API response structure
• DotCMSAISearchContentletData<T> - Contentlet with AI match information
• DotCMSAISearchMatch - Individual match with distance score and extracted text
• DotErrorAISearch - AI Search API specific error with prompt, indexName, and params context
• DISTANCE_FUNCTIONS - Available distance functions for vector similarity (cosine, L2, inner product, etc.)

[1.1.1]

Added

• DotHttpClient interface for custom HTTP client implementations
• BaseHttpClient abstract class with built-in error handling utilities
• DotHttpError class for standardized HTTP error handling
• DotErrorPage class for page-specific errors with GraphQL query context
• DotErrorContent class for content API errors with operation details
• DotErrorNavigation class for navigation-specific error handling
• DotGraphQLApiResponse interface for GraphQL API responses
• HttpErrorDetails interface for HTTP error standardization
• All error classes include toJSON() methods for easy logging and serialization

Changed

• Renamed RequestOptions to DotRequestOptions for better naming consistency
• Renamed DotCMSGraphQLPageResponse to DotGraphQLApiResponse for clarity
• Enhanced DotCMSClientConfig to support custom httpClient implementations

Licensing

dotCMS is available under either the Business Source License 1.1 (BSL) or a commercial license.

Under the BSL, dotCMS can be used at no cost by individual developers, small businesses or agencies under $5M in total finances, and by larger organizations in non-production environments. Every BSL release automatically converts to GPL v3 four years after its release date. For full terms and FAQs, visit dotcms.com/bsl and dotcms.com/bsl-faq.

Production use in larger organizations, along with access to managed cloud, SLAs, support, and enterprise capabilities, is available under a commercial license from dotCMS. For details on commercial plans, features, and support options, see dotcms.com/pricing.