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