{"id":15587,"library":"datocms-client","title":"DatoCMS Content Management API Client (Deprecated)","description":"The `datocms-client` npm package is a JavaScript client library for interacting with the DatoCMS Content Management API (CMA). It allows developers to programmatically manage content, schemas, and assets within a DatoCMS project. This package is **officially deprecated** as of April 2022, with the last stable version being 3.5.24, published approximately two years ago. The DatoCMS team strongly recommends migrating to the new, fully TypeScript-ready client, `@datocms/cma-client-node` for Node.js environments or `@datocms/cma-client-browser` for browser environments. The new clients offer better type safety, ESM readiness, a smaller package size, and improved file upload methods. This deprecated client will not receive further updates and may experience breaking changes due to ongoing API evolution.","status":"deprecated","version":"3.5.24","language":"javascript","source_language":"en","source_url":"git://github.com/datocms/js-datocms-client","tags":["javascript","datocms","cms","metalsmith","hexo"],"install":[{"cmd":"npm install datocms-client","lang":"bash","label":"npm"},{"cmd":"yarn add datocms-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add datocms-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is the primary class for interacting with the DatoCMS Content Management API using the *deprecated* client. Prefer named imports even for deprecated packages.","wrong":"const SiteClient = require('datocms-client').SiteClient;","symbol":"SiteClient","correct":"import { SiteClient } from 'datocms-client';"},{"note":"Used for constructing modular block data when creating or updating items with the *deprecated* client. Ensure you are handling modular blocks correctly as API behavior for them has changed.","symbol":"buildModularBlock","correct":"import { buildModularBlock } from 'datocms-client';"}],"quickstart":{"code":"import { SiteClient } from 'datocms-client';\n\n// ⚠️ WARNING: This package is DEPRECATED. Please migrate to @datocms/cma-client-node.\n// See: https://www.datocms.com/docs/content-management-api/using-the-nodejs-clients\n\nconst API_TOKEN = process.env.DATOCMS_API_TOKEN ?? '';\n\nif (!API_TOKEN) {\n  console.error('DATOCMS_API_TOKEN environment variable is not set.');\n  process.exit(1);\n}\n\nasync function createItemWithDeprecatedClient() {\n  try {\n    const client = new SiteClient(API_TOKEN, { \n      // 'logApiCalls' is an option available in the deprecated client\n      // It logs API requests and responses.\n      logApiCalls: true\n    });\n\n    console.log('--- Using deprecated datocms-client ---');\n    // Example: Fetch existing item types\n    const itemTypes = await client.itemTypes.all();\n    console.log(`Found ${itemTypes.length} item types. Example: ${itemTypes[0]?.api_key}`);\n\n    // Example: Create a new item (simplified, usually requires more fields)\n    // This operation might be subject to the 'id' not permitted key issue.\n    // const newItem = await client.items.create({\n    //   itemType: itemTypes[0].id, // Use an existing item type ID\n    //   title: `My Deprecated Item ${Date.now()}`,\n    //   // ... other fields\n    // });\n    // console.log('Created item:', newItem.id);\n\n  } catch (error) {\n    console.error('Error using deprecated datocms-client:', error);\n    if (error.findError) {\n      console.error('API Error details:', error.findError('INVALID_FIELD'));\n    }\n  }\n}\n\ncreateItemWithDeprecatedClient();\n\n/*\n// Recommended alternative using @datocms/cma-client-node (install separately):\n// npm install @datocms/cma-client-node\n\n// import { buildClient } from '@datocms/cma-client-node';\n\n// async function createItemWithNewClient() {\n//   try {\n//     const client = buildClient({ apiToken: API_TOKEN });\n//     console.log('\\n--- Using recommended @datocms/cma-client-node ---');\n//     const itemTypes = await client.itemTypes.list(); // Note: method names might differ (all vs list)\n//     console.log(`Found ${itemTypes.length} item types. Example: ${itemTypes[0]?.api_key}`);\n\n//     // Example: Create a new item (requires a valid item type ID from your DatoCMS project)\n//     // const modelId = itemTypes.find(mt => mt.api_key === 'article')?.id; // Find an existing model\n//     // if (modelId) {\n//     //   const newItem = await client.items.create({\n//     //     item_type: { type: 'item_type', id: modelId },\n//     //     attributes: { title: `My New Item ${Date.now()}` }\n//     //   });\n//     //   console.log('Created item with new client:', newItem.id);\n//     // }\n\n//   } catch (error) {\n//     console.error('Error using new DatoCMS client:', error);\n//   }\n// }\n\n// createItemWithNewClient();\n*/","lang":"typescript","description":"Demonstrates basic initialization and fetching item types using the deprecated `datocms-client`. Includes a strong warning about its deprecation and outlines the recommended migration path."},"warnings":[{"fix":"Migrate your codebase to use the new DatoCMS JavaScript CMA clients: `@datocms/cma-client-node` for Node.js or `@datocms/cma-client-browser` for browsers. Install the new package and refactor your API calls according to the updated documentation.","message":"The `datocms-client` package is officially deprecated and is no longer maintained. It will not receive new features, bug fixes, or security updates. Developers should migrate to `@datocms/cma-client-node` or `@datocms/cma-client-browser` immediately.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure all modular block operations are performed by modifying the parent item's modular content field. This change affects how `datocms-client` users interact with modular content programmatically.","message":"Direct creation, duplication, updating, or deletion of modular block items using legacy endpoints (`POST /items`, `PUT /items/:id`, etc.) was deprecated as of February 1st, 2020. Operations on modular block items must now be done by updating the modular content field on the parent item.","severity":"breaking","affected_versions":"<3.0.0"},{"fix":"As a temporary workaround for the deprecated client, you can pass `{ serializeRequest: false }` as an option to `item.publish()`. However, the permanent fix is to upgrade to `@datocms/cma-client-node` where this issue is resolved and `item.publish()` without a body publishes the entire record.","message":"When using `item.publish()` with the deprecated `datocms-client`, a known issue exists where passing an empty body (`{}`) can result in an error: \"`id` is not a permitted key\". The deprecated client's internal serialization rules may cause this.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Use the new `isPresent` filter, which selects values that are neither `null` nor empty strings, or `isBlank` for its opposite. While the `exists` filter still works for now, it will be removed in future API versions.","message":"The `exists` filter for string, text, and Structured Text fields in the DatoCMS Content Delivery API (CDA) is deprecated. It previously returned empty strings instead of `null` values, leading to confusing behavior.","severity":"deprecated","affected_versions":"N/A (API-level deprecation, affects all clients)"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"With the deprecated client, pass `{ serializeRequest: false }` as the fourth argument to `client.items.publish(itemId, {}, {}, { serializeRequest: false })`. For a long-term solution, migrate to `@datocms/cma-client-node` and use `client.items.publish(itemId)` without any body.","cause":"This error occurs when attempting to use `item.publish()` with the deprecated `datocms-client` and passing an empty object as the request body, which triggers an old serialization bug.","error":"#/data: failed schema #/definitions/item/links/13/schema/properties/data: \"id\" is not a permitted key."},{"fix":"The new `@datocms/cma-client-node` offers specialized helper methods like `createFromLocalFile()` and `createFromUrl()` that are robustly designed for Node.js file system access. For browser environments, `@datocms/cma-client-browser` provides `createFromFileOrBlob()`. Use the appropriate modern client for reliable file uploads.","cause":"The deprecated `datocms-client` may have inconsistent or limited support for file system operations in various environments, particularly when handling local file uploads.","error":"Error: ENODEV: no such device or address, unlink './image.png'"}],"ecosystem":"npm"}