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.
createClients
✓ import { createClients } from 'contentful-batch-libs';
✗ const { createClients } = require('contentful-batch-libs');
The library is primarily designed for ESM usage since v11 due to Node.js v22+ requirement, though older versions might have supported CommonJS.
getSourceSpace
✓ import { getSourceSpace } from 'contentful-batch-libs';
Used to retrieve content from a Contentful space for further manipulation or copying.
pushToSpace
✓ import { pushToSpace } from 'contentful-batch-libs';
This function is central for applying batch changes, including creations, updates, deletions, and publishing, to a target Contentful space.
This quickstart demonstrates how to initialize Contentful clients, fetch all content from a source space, and then push that content (or transformed content) back to a target space using `contentful-batch-libs`.
import { createClients, getSourceSpace, pushToSpace } from 'contentful-batch-libs';
const SPACE_ID = process.env.CONTENTFUL_SOURCE_SPACE_ID ?? '';
const MANAGEMENT_TOKEN = process.env.CONTENTFUL_MANAGEMENT_TOKEN ?? '';
const DELIVERY_TOKEN = process.env.CONTENTFUL_DELIVERY_TOKEN ?? '';
const ENVIRONMENT_ID = process.env.CONTENTFUL_ENVIRONMENT_ID ?? 'master';
if (!SPACE_ID || !MANAGEMENT_TOKEN || !DELIVERY_TOKEN) {
console.error('Environment variables CONTENTFUL_SOURCE_SPACE_ID, CONTENTFUL_MANAGEMENT_TOKEN, and CONTENTFUL_DELIVERY_TOKEN must be set.');
process.exit(1);
}
async function runBatchOperation() {
try {
// 1. Create Contentful client instances
const { managementClient, deliveryClient } = createClients({
spaceId: SPACE_ID,
managementToken: MANAGEMENT_TOKEN,
accessToken: DELIVERY_TOKEN,
environmentId: ENVIRONMENT_ID,
});
console.log('Contentful clients created successfully.');
// 2. Get content from the source space
console.log(`Fetching content from space '${SPACE_ID}'...`);
const sourceContent = await getSourceSpace({
managementClient,
deliveryClient,
spaceId: SPACE_ID,
environmentId: ENVIRONMENT_ID,
// You might want to specify content types, entries, assets, etc. to fetch
// For example: query: { 'content_type': 'blogPost' }
});
console.log(`Fetched ${sourceContent.entries.length} entries and ${sourceContent.assets.length} assets.`);
// 3. (Optional) Transform content here if needed
// const transformedContent = transformSpace(sourceContent, /* transformers */);
// 4. Push transformed or original content to a destination space (example uses the same space ID for simplicity)
// In a real scenario, you'd likely have a separate destination space ID and clients.
console.log(`Pushing content back to space '${SPACE_ID}'...`);
await pushToSpace({
sourceContent,
managementClient,
spaceId: SPACE_ID,
environmentId: ENVIRONMENT_ID,
// Optional: publish: false, contentModelOnly: true, etc.
});
console.log('Batch operation completed successfully.');
} catch (error) {
console.error('An error occurred during the batch operation:', error);
process.exit(1);
}
}
runBatchOperation();
Errors
Common errors & fixes
ERR_REQUIRE_ESM: require() of ES Module ... from ... not supported.
Attempting to use `require()` to import a module from `contentful-batch-libs` in a CommonJS context when the library is published as an ESM module.
fixConvert your project or the specific file to use ESM imports: `import { createClients } from 'contentful-batch-libs';`. Ensure your `package.json` has `"type": "module"` if running in Node.js, or use a bundler that handles ESM correctly. Error: Node.js vX.Y.Z is not supported. Please upgrade to Node.js >=22.
Running `contentful-batch-libs` on a Node.js version older than the minimum required version (Node.js 22+ since v11.0.0).
fixUpgrade your Node.js installation to version 22 or newer. Use a tool like `nvm` to manage Node.js versions: `nvm install 22 && nvm use 22`.
Audit
Dependencies
contentful-managementrequiredRequired for programmatic interaction with the Contentful Management API to perform batch operations.
contentfulrequiredRequired for programmatic interaction with the Contentful Delivery API.