JodusNodus

datocms

Expert guidance for building with DatoCMS headless CMS. Includes API decision guides (CDA vs CMA), executable workflow playbooks for schema management, content operations, asset uploads, migrations, structured text (DAST), webhooks, and framework integrations. Covers official MCP server integration and troubleshooting.

JodusNodus 0 Updated 3mo ago
GitHub

Install

npx skillscat add jodusnodus/datocms-skill/datocms

Install via the SkillsCat registry.

SKILL.md

DatoCMS Agent Skill

This skill provides comprehensive guidance for working with DatoCMS, a headless CMS platform. It combines decision frameworks, executable workflows, and complete documentation reference.

When to Use This Skill

Use this skill when:

  • Building or maintaining a DatoCMS project
  • Integrating DatoCMS with frameworks (Next.js, React, Vue, etc.)
  • Managing content models, records, or assets via API
  • Setting up webhooks or real-time updates
  • Working with DatoCMS plugins or the Plugin SDK
  • Migrating content or managing multiple environments
  • Troubleshooting DatoCMS API or integration issues

Do NOT use this skill for:

  • Generic CMS comparisons (unless DatoCMS-specific)
  • Non-DatoCMS headless CMS implementations
  • Basic frontend development unrelated to DatoCMS

API Decision Guide

DatoCMS provides multiple APIs for different use cases:

Content Delivery API (CDA)

Use for: Fetching published content for production sites

  • GraphQL-based, read-only
  • Optimized for speed with global CDN
  • Supports filtering, sorting, pagination
  • Best for: SSR, SSG, client-side fetching

Example:

import { executeQuery } from '@datocms/cda-client';

const result = await executeQuery(query, {
  token: process.env.DATOCMS_API_TOKEN,
  environment: 'main'
});

Content Management API (CMA)

Use for: Creating, updating, deleting content and schema

  • REST-based with full CRUD operations
  • Requires write permissions
  • Best for: Admin panels, migrations, automated content creation

Example:

import { buildClient } from '@datocms/cma-client-node';

const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });

// Create a record
const record = await client.items.create({
  item_type: { type: 'item_type', id: 'blog_post' },
  title: 'New Post',
  content: 'Content here'
});

Asset API

Use for: Uploading files and managing assets

  • Two-step process: request upload URL, then upload file
  • Supports images, videos, documents

Real-Time Updates API

Use for: Live preview, collaborative editing

  • WebSocket-based
  • Reflects draft changes instantly

Getting Started

1. API Tokens

  • Go to Settings > API Tokens in your DatoCMS project
  • Read-only token for CDA (can be public)
  • Full-access token for CMA (keep secret)

2. Install Clients

# For content fetching
npm install @datocms/cda-client

# For content management
npm install @datocms/cma-client-node

# For React/Next.js
npm install react-datocms

3. Basic Query

import { executeQuery } from '@datocms/cda-client';

const query = `
  query {
    allBlogPosts {
      id
      title
      slug
      publishedAt
    }
  }
`;

const data = await executeQuery(query, {
  token: process.env.DATOCMS_API_TOKEN
});

Workflow Playbooks

1. Schema Management: Create Models & Fields

When: Setting up new content types or modifying existing ones

import { buildClient } from '@datocms/cma-client-node';

const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });

// Create a model
const model = await client.itemTypes.create({
  name: 'Blog Post',
  api_key: 'blog_post',
  singleton: false
});

// Add fields
await client.fields.create(model.id, {
  label: 'Title',
  field_type: 'string',
  api_key: 'title',
  validators: { required: {} }
});

await client.fields.create(model.id, {
  label: 'Content',
  field_type: 'structured_text',
  api_key: 'content'
});

2. Content Operations: CRUD + Publishing

When: Managing content records programmatically

// Create draft
const draft = await client.items.create({
  item_type: { type: 'item_type', id: 'blog_post' },
  title: 'My Post',
  content: { /* DAST structure */ }
});

// Update
await client.items.update(draft.id, {
  title: 'Updated Title'
});

// Publish
await client.items.publish(draft.id);

// Unpublish
await client.items.unpublish(draft.id);

// Delete
await client.items.destroy(draft.id);

3. Asset Uploads: Two-Step Flow

When: Uploading images, videos, or documents

import { buildClient } from '@datocms/cma-client-node';
import fs from 'fs';

const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });

// Step 1: Create upload request
const path = './image.jpg';
const uploadRequest = await client.uploads.createFromFileOrBlob({
  fileOrBlob: fs.createReadStream(path),
  filename: 'image.jpg'
});

// Step 2: Use upload in a record
await client.items.create({
  item_type: { type: 'item_type', id: 'blog_post' },
  title: 'Post with Image',
  cover_image: {
    upload_id: uploadRequest.id
  }
});

4. Migrations: Sandbox to Production

When: Testing schema changes before deploying

# Create sandbox environment
# (Do this in DatoCMS UI: Settings > Environments)

# Make changes in sandbox
DATOCMS_ENVIRONMENT=sandbox node update-schema.js

# Test in sandbox
# Preview at: https://your-project.admin.datocms.com/editor?environment=sandbox

# Promote to primary environment (via UI or API)

5. Structured Text (DAST): Handling Rich Content

When: Working with rich text fields

import { render } from 'datocms-structured-text-to-html-string';

// DAST structure
const structuredText = {
  schema: 'dast',
  document: {
    type: 'root',
    children: [
      {
        type: 'heading',
        level: 1,
        children: [{ type: 'span', value: 'Hello World' }]
      },
      {
        type: 'paragraph',
        children: [
          { type: 'span', value: 'This is ' },
          { type: 'span', marks: ['strong'], value: 'bold text' }
        ]
      }
    ]
  }
};

// Render to HTML
const html = render(structuredText);

6. Webhooks: Event Notifications

When: Triggering builds or syncing data on content changes

// Create webhook via CMA
const webhook = await client.webhooks.create({
  name: 'Deploy on Publish',
  url: 'https://api.vercel.com/v1/integrations/deploy/...',
  events: [
    { entity_type: 'item', event_types: ['publish', 'unpublish'] }
  ],
  http_basic_user: 'user',
  http_basic_password: 'pass'
});

7. Framework Integration: Next.js Example

When: Building a Next.js site with DatoCMS

// app/blog/page.tsx
import { executeQuery } from '@datocms/cda-client';

const query = `
  query {
    allBlogPosts(orderBy: publishedAt_DESC) {
      id
      title
      slug
      excerpt
    }
  }
`;

export default async function BlogPage() {
  const { allBlogPosts } = await executeQuery(query, {
    token: process.env.DATOCMS_API_TOKEN!
  });

  return (
    <div>
      {allBlogPosts.map(post => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <p>{post.excerpt}</p>
        </article>
      ))}
    </div>
  );
}

MCP Server Integration

DatoCMS provides an official Model Context Protocol (MCP) server for AI agents:

Installation

{
  "mcpServers": {
    "datocms": {
      "command": "npx",
      "args": ["-y", "@datocms/mcp-server"],
      "env": {
        "DATOCMS_API_TOKEN": "your-full-access-token"
      }
    }
  }
}

Available Tools

  • list_models - List all content models
  • get_model - Get model details with fields
  • list_records - List records of a model
  • get_record - Get single record by ID
  • create_record - Create new record
  • update_record - Update existing record
  • delete_record - Delete record

Troubleshooting

Common Issues

1. "Invalid API token"

  • Verify token in Settings > API Tokens
  • Check environment variable is loaded
  • Ensure token has required permissions (read-only vs full-access)

2. "Model/Field not found"

  • Use api_key not id in queries
  • Check model exists in current environment
  • Verify field spelling and case sensitivity

3. "Rate limit exceeded"

  • CDA: 30 requests/second (burst: 60)
  • CMA: 15 requests/second
  • Implement exponential backoff

4. Asset upload fails

  • Check file size limits (5GB max)
  • Verify file type is supported
  • Use createFromFileOrBlob method

5. Structured text not rendering

  • Validate DAST schema structure
  • Use official rendering packages
  • Check for custom block types

Debug Checklist

  • API token is correct and has required permissions
  • Environment name matches (main vs sandbox)
  • API key names match schema (not display names)
  • Request payload matches API documentation
  • Check DatoCMS status page for outages
  • Review API logs in DatoCMS settings

Documentation Reference

Below is the complete index of DatoCMS documentation organized by topic. All links point to Markdown versions for easy parsing.

DatoCMS

Docs

Official packages READMEs

Categories

API Dev Docs Gen Writing
GitHub

Install

npx skillscat add jodusnodus/datocms-skill/datocms

Install via the SkillsCat registry.

Recommended Skills

olaxbt
AI Market Maker Skill by olaxbt
1.3K 1mo ago
mukul975
analyzing-android-malware-with-apktool by mukul975
12.5K 1mo ago
mukul975
analyzing-malware-behavior-with-cuckoo-sandbox by mukul975
12.6K 3mo ago
mukul975
analyzing-malware-family-relationships-with-malpedia by mukul975
12.5K 3mo ago
K-Dense-AI
alpha-vantage by K-Dense-AI
26.6K 3mo ago
Chachamaru127
ci by Chachamaru127
2.3K 3mo ago