@platecms/delta-client

Utilities and functions to interact with the Delta CMS.

Overview

The @platecms/delta-client package provides a comprehensive set of utilities for working with the Delta CMS. It includes schema parsing, Slate.js integration, Apollo Client setup, and various helper functions for content management.

Installation

npm install @platecms/delta-client

Package Structure

This package is organized into several main modules:

📦 Main Exports

• @platecms/delta-client - Main package entry point
• @platecms/delta-client/slate - Slate.js integration and type definitions
• @platecms/delta-client/schema - Schema parsing and validation utilities
• @platecms/delta-client/apollo - Apollo Client configuration and setup

Features

🎯 Schema Parsing (/schema)

The schema module provides a powerful type-safe way to parse and validate content from the Delta CMS.

Basic Usage

import { schema } from '@platecms/delta-client/schema';

// Define a content structure
const articleSchema = schema.buildingBlock({
  // Multiple types for a field
  title: [schema.string(), schema.number()],
  content: schema.smartText(),
  publishedAt: schema.date(),
  featured: schema.boolean(),
  // Array of items
  tags: schema.array(schema.tag()),
  // For related content items
  author: schema.contentItem({
    name: schema.string(),
    email: schema.string(),
  }),
});

// Parse content data
const article = articleSchema.parse(buildingBlockFieldFulfillments);

// Result
{
    title: "My article",
    content: {
        type: "root",
        children: [
            {
                type: "paragraph",
                children: [
                    {
                        type: "text",
                        value: "My first article"
                    }
                ]
            }
        ]
    },
    publishedAt: new Date(),
    featured: true,
    tags: [{
        name: "Higlighted",
        //...other tag fields
    }],
    author: {
        name: "Plate",
        email: "[email protected]"
    }
}

Available Types

• schema.string() - String values
• schema.number() - Numeric values
• schema.boolean() - Boolean values
• schema.date() - Date values
• schema.asset() - Asset references
• schema.smartText() - Rich text content
• schema.contentItem() - Related content items
• schema.buildingBlock() - Building block structures
• schema.array() - Arrays of any schema
• schema.gridPlacement() - Grid layout placements
• schema.contentType() - Content type references
• schema.pathPart() - URL path components
• schema.tag() - Tag references

Advanced Features

// Nullable fields with placeholders
const schema = schema.contentItem({
  title: schema.string().nullable(false), // Required field, throws
  description: schema.string().placeholder("No description available"), // Default value
});

// Array handling
const tagsSchema = schema.array(schema.tag());

// Array handling with placeholders
const tagsSchema = schema.array(
  schema.string().placeholder('placeholder')
).placeholder({ minLength: 1 });

// Nested structures
const pageSchema = schema.buildingBlock({
  hero: schema.contentItem({
    title: schema.string(),
    image: schema.asset(),
  }),
  sections: schema.array(schema.contentItem({
    type: schema.string(),
    content: schema.smartText(),
  })),
});

🎨 Slate.js Integration (/slate)

Provides TypeScript definitions and utilities for working with Slate.js in the Delta CMS context.

Type Definitions

import { DeltaElement, DeltaLeaf } from '@platecms/delta-client/slate';

// Available element types
type DeltaElement = 
  | ParagraphElement
  | HeadingElement  
  | ListElement
  | ListItemElement
  | BlockquoteElement
  | CodeElement
  | ContentValueElement
  | LinkElement;

// Leaf node with formatting
type DeltaLeaf = {
  text: string;
  bold?: true;
  italic?: true;
  underline?: true;
  strikethrough?: true;
  inlineCode?: true;
  highlight?: true;
  title?: true;
};

🚀 Apollo Client Setup (/apollo)

Pre-configured Apollo Client for GraphQL communication with Delta CMS.

Basic Setup

import { createApolloClient } from '@platecms/delta-client/apollo';

const client = createApolloClient('https://api.delta-cms.com/graphql', {
  name: 'delta-cms-client',
  headers: {
    'Authorization': 'Bearer your-token',
  },
});

Advanced Configuration

import { createApolloClient } from '@platecms/delta-client/apollo';
import { onError } from '@apollo/client/link/error';

const errorLink = onError(({ graphQLErrors, networkError }) => {
  if (graphQLErrors) {
    graphQLErrors.forEach(({ message, locations, path }) =>
      console.log(`GraphQL error: Message: ${message}, Location: ${locations}, Path: ${path}`)
    );
  }
});

const client = createApolloClient('https://api.delta-cms.com/graphql', {
  name: 'delta-cms-client',
  errorLink,
  headers: {
    'X-Custom-Header': 'value',
  },
});

🛠️ Utilities (/utils)

Helper functions and connectors for Delta CMS integration.

Connectors

import { WindowConnector, ConnectorEvents } from '@platecms/delta-client/utils';

// Window-based communication
const connector = new WindowConnector();
connector.on(ConnectorEvents.CONTENT_UPDATED, (data) => {
  console.log('Content updated:', data);
});

Draft Types

import { Draft } from '@platecms/delta-client/utils';

type DraftArticle = Draft<{
  title: string;
  content: string;
}>;

// Draft objects include isDraft and uuid properties
const draft: DraftArticle = {
  title: "My Article",
  content: "Article content...",
  isDraft: true,
  uuid: "123e4567-e89b-12d3-a456-426614174000",
};

API Reference

Schema schemas

All schemas support the following methods:

• .nullable(boolean) - Set whether the field can be null
• .placeholder(value) - Set default value when data is missing
• .parse(data, config?) - Parse data with optional configuration

Configuration Options

interface schemaConfig {
  placeholders?: boolean; // Enable placeholder values
}

Apollo Client Options

interface ApolloClientOptions {
  name?: string;
  errorLink?: ApolloLink;
  headers?: Record<string, string>;
}

Examples

Complete Content Parsing Example

import { schema } from '@platecms/delta-client/schema';
import { createApolloClient } from '@platecms/delta-client/apollo';

// Define schema
const blogPostSchema = schema.contentItem({
  title: schema.string().nullable(false),
  excerpt: schema.string().placeholder("No excerpt available"),
  content: schema.smartText(),
  author: schema.contentItem({
    name: schema.string(),
    avatar: schema.asset(),
  }),
  tags: schema.array(schema.tag()).placeholder({
    minLength: 1
  }),
  publishedAt: schema.date(),
  featured: schema.boolean().placeholder(false),
});

// Setup Apollo Client
const client = createApolloClient('https://api.delta-cms.com/graphql');

// Parse content
const blogPost = blogPostSchema.parse(contentValue, { placeholders: true });

Slate.js Editor Integration

import { BaseEditor } from 'slate';
import { ReactEditor } from 'slate-react';
import { DeltaElement, DeltaLeaf } from '@platecms/delta-client/slate';

// Type your editor
type CustomEditor = BaseEditor & ReactEditor;

// Use in your editor component
const MyEditor = () => {
  const editor = useMemo(() => withReact(createEditor()), []);
  
  // Your editor implementation
  return (
    <Slate editor={editor} value={value} onChange={setValue}>
      <Editable />
    </Slate>
  );
};

Dependencies

Peer Dependencies

• @platecms/delta-cast - Core casting utilities
• @graphql-typed-document-node/core - GraphQL type safety
• graphql - GraphQL implementation
• slate - Rich text editor framework
• slate-react - React integration for Slate
• tslib - TypeScript runtime library
• class-transformer - Object transformation
• reflect-metadata - Metadata reflection
• @apollo/client - GraphQL client
• defu - Object merging utility

Development

This package is part of the Delta monorepo and uses Nx for build orchestration.

Building

nx build delta-client

Testing

nx test delta-client

Linting

nx lint delta-client

Repository

• Homepage: https://bitbucket.org/startmetplate/delta/src/dev/packages/delta-client
• Repository: https://bitbucket.org/startmetplate/delta.git