@dotcms/types

DotCMS Type Definition Library

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

Installation

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

Overview

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

Table of Contents

• Installation
• Overview
• Commonly Used Types
• Type Hierarchy (Jump to Definitions)
  • dotCMS Content & Pages
  • Universal Visual Editor (UVE)
  • Block Editor
  • Client & HTTP
  • Error Handling
• Type Usage
  • Error Type Checking
• About
• Changelog

Commonly Used Types

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

Type Hierarchy (Jump to Definitions)

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

Type Usage

Error Type Checking

import {
  DotHttpError,
  DotErrorPage,
  DotErrorContent,
  DotErrorNavigation
} 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}`);
}

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

About

This package is maintained as part of the dotCMS core repository.

Keywords

• dotcms
• typescript
• types
• cms
• content-management-system

Changelog

[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