Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SiteClient
✓ import { SiteClient } from 'datocms-client';
✗ const SiteClient = require('datocms-client').SiteClient;
This is the primary class for interacting with the DatoCMS Content Management API using the *deprecated* client. Prefer named imports even for deprecated packages.
buildModularBlock
✓ import { buildModularBlock } from 'datocms-client';
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.
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.
import { SiteClient } from 'datocms-client';
// ⚠️ WARNING: This package is DEPRECATED. Please migrate to @datocms/cma-client-node.
// See: https://www.datocms.com/docs/content-management-api/using-the-nodejs-clients
const API_TOKEN = process.env.DATOCMS_API_TOKEN ?? '';
if (!API_TOKEN) {
console.error('DATOCMS_API_TOKEN environment variable is not set.');
process.exit(1);
}
async function createItemWithDeprecatedClient() {
try {
const client = new SiteClient(API_TOKEN, {
// 'logApiCalls' is an option available in the deprecated client
// It logs API requests and responses.
logApiCalls: true
});
console.log('--- Using deprecated datocms-client ---');
// Example: Fetch existing item types
const itemTypes = await client.itemTypes.all();
console.log(`Found ${itemTypes.length} item types. Example: ${itemTypes[0]?.api_key}`);
// Example: Create a new item (simplified, usually requires more fields)
// This operation might be subject to the 'id' not permitted key issue.
// const newItem = await client.items.create({
// itemType: itemTypes[0].id, // Use an existing item type ID
// title: `My Deprecated Item ${Date.now()}`,
// // ... other fields
// });
// console.log('Created item:', newItem.id);
} catch (error) {
console.error('Error using deprecated datocms-client:', error);
if (error.findError) {
console.error('API Error details:', error.findError('INVALID_FIELD'));
}
}
}
createItemWithDeprecatedClient();
/*
// Recommended alternative using @datocms/cma-client-node (install separately):
// npm install @datocms/cma-client-node
// import { buildClient } from '@datocms/cma-client-node';
// async function createItemWithNewClient() {
// try {
// const client = buildClient({ apiToken: API_TOKEN });
// console.log('\n--- Using recommended @datocms/cma-client-node ---');
// const itemTypes = await client.itemTypes.list(); // Note: method names might differ (all vs list)
// console.log(`Found ${itemTypes.length} item types. Example: ${itemTypes[0]?.api_key}`);
// // Example: Create a new item (requires a valid item type ID from your DatoCMS project)
// // const modelId = itemTypes.find(mt => mt.api_key === 'article')?.id; // Find an existing model
// // if (modelId) {
// // const newItem = await client.items.create({
// // item_type: { type: 'item_type', id: modelId },
// // attributes: { title: `My New Item ${Date.now()}` }
// // });
// // console.log('Created item with new client:', newItem.id);
// // }
// } catch (error) {
// console.error('Error using new DatoCMS client:', error);
// }
// }
// createItemWithNewClient();
*/
Debug
Known issues
breakingThe `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.fixMigrate 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.
affects: >=3.0.0
breakingDirect 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.fixEnsure 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.
affects: <3.0.0
gotchaWhen 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.fixAs 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. affects: >=3.0.0
deprecatedThe `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.fixUse 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.
affects: N/A (API-level deprecation, affects all clients)
Errors
Common errors & fixes
#/data: failed schema #/definitions/item/links/13/schema/properties/data: "id" is not a permitted key.
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.
fixWith 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. Error: ENODEV: no such device or address, unlink './image.png'
The deprecated `datocms-client` may have inconsistent or limited support for file system operations in various environments, particularly when handling local file uploads.
fixThe 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.
Audit
Dependencies
No dependency data recorded yet.