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

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

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:

AI Search Response:

AI Search Errors:

dotCMS Content & Pages#

Page:

Content:

Site & Layout:

Navigation:

Universal Visual Editor (UVE)#

Editor State:

Editor Events:

Inline Editing:

Block Editor#

Client & HTTP#

HTTP Client:

Client Configuration:

Error Handling#

Base Error Types:

Domain-Specific Errors:

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

This package is part of dotCMS's dual-licensed platform (GPL 3.0 for Community, commercial license for Enterprise).