{"id":10665,"library":"contentful-batch-libs","title":"Contentful Batch Utilities Library","description":"This library provides core modules and shared methods utilized by Contentful's batch utility CLI tools, specifically for `contentful-import` and `contentful-export`. It offers low-level programmatic access to operations such as getting source content from a space, pushing changes (including deletions, creations, and publishing/unpublishing) to a destination space, and various content transformations. It also includes utilities for creating Contentful clients and error handling. The current stable version is 11.0.0. The project uses `semantic-release`, indicating a release cadence of frequent patch/minor versions and major versions only for breaking changes. Its key differentiator lies in providing granular, batch-oriented control over Contentful space manipulation, acting as a foundational layer for more complex data migration and synchronization workflows between Contentful environments.","status":"active","version":"11.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/contentful/contentful-batch-libs","tags":["javascript","contentful","batch","typescript"],"install":[{"cmd":"npm install contentful-batch-libs","lang":"bash","label":"npm"},{"cmd":"yarn add contentful-batch-libs","lang":"bash","label":"yarn"},{"cmd":"pnpm add contentful-batch-libs","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for programmatic interaction with the Contentful Management API to perform batch operations.","package":"contentful-management","optional":false},{"reason":"Required for programmatic interaction with the Contentful Delivery API.","package":"contentful","optional":false}],"imports":[{"note":"The library is primarily designed for ESM usage since v11 due to Node.js v22+ requirement, though older versions might have supported CommonJS.","wrong":"const { createClients } = require('contentful-batch-libs');","symbol":"createClients","correct":"import { createClients } from 'contentful-batch-libs';"},{"note":"Used to retrieve content from a Contentful space for further manipulation or copying.","symbol":"getSourceSpace","correct":"import { getSourceSpace } from 'contentful-batch-libs';"},{"note":"This function is central for applying batch changes, including creations, updates, deletions, and publishing, to a target Contentful space.","symbol":"pushToSpace","correct":"import { pushToSpace } from 'contentful-batch-libs';"}],"quickstart":{"code":"import { createClients, getSourceSpace, pushToSpace } from 'contentful-batch-libs';\n\nconst SPACE_ID = process.env.CONTENTFUL_SOURCE_SPACE_ID ?? '';\nconst MANAGEMENT_TOKEN = process.env.CONTENTFUL_MANAGEMENT_TOKEN ?? '';\nconst DELIVERY_TOKEN = process.env.CONTENTFUL_DELIVERY_TOKEN ?? '';\nconst ENVIRONMENT_ID = process.env.CONTENTFUL_ENVIRONMENT_ID ?? 'master';\n\nif (!SPACE_ID || !MANAGEMENT_TOKEN || !DELIVERY_TOKEN) {\n  console.error('Environment variables CONTENTFUL_SOURCE_SPACE_ID, CONTENTFUL_MANAGEMENT_TOKEN, and CONTENTFUL_DELIVERY_TOKEN must be set.');\n  process.exit(1);\n}\n\nasync function runBatchOperation() {\n  try {\n    // 1. Create Contentful client instances\n    const { managementClient, deliveryClient } = createClients({\n      spaceId: SPACE_ID,\n      managementToken: MANAGEMENT_TOKEN,\n      accessToken: DELIVERY_TOKEN,\n      environmentId: ENVIRONMENT_ID,\n    });\n\n    console.log('Contentful clients created successfully.');\n\n    // 2. Get content from the source space\n    console.log(`Fetching content from space '${SPACE_ID}'...`);\n    const sourceContent = await getSourceSpace({\n      managementClient,\n      deliveryClient,\n      spaceId: SPACE_ID,\n      environmentId: ENVIRONMENT_ID,\n      // You might want to specify content types, entries, assets, etc. to fetch\n      // For example: query: { 'content_type': 'blogPost' }\n    });\n\n    console.log(`Fetched ${sourceContent.entries.length} entries and ${sourceContent.assets.length} assets.`);\n\n    // 3. (Optional) Transform content here if needed\n    // const transformedContent = transformSpace(sourceContent, /* transformers */);\n\n    // 4. Push transformed or original content to a destination space (example uses the same space ID for simplicity)\n    // In a real scenario, you'd likely have a separate destination space ID and clients.\n    console.log(`Pushing content back to space '${SPACE_ID}'...`);\n    await pushToSpace({\n      sourceContent,\n      managementClient,\n      spaceId: SPACE_ID,\n      environmentId: ENVIRONMENT_ID,\n      // Optional: publish: false, contentModelOnly: true, etc.\n    });\n\n    console.log('Batch operation completed successfully.');\n  } catch (error) {\n    console.error('An error occurred during the batch operation:', error);\n    process.exit(1);\n  }\n}\n\nrunBatchOperation();\n","lang":"typescript","description":"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`."},"warnings":[{"fix":"Upgrade your Node.js environment to version 22 or higher. For example, use `nvm install 22 && nvm use 22`.","message":"Node.js versions older than 22 are no longer supported. The `engines.node` minimum has been raised to `>=22` starting with v11.0.0. Ensure your runtime environment meets this requirement before upgrading.","severity":"breaking","affected_versions":">=11.0.0"},{"fix":"Avoid `v10.1.7`. Upgrade directly to `v11.0.0` or later, ensuring Node.js `>=22` is in use.","message":"Version `v10.1.7` contained the Node.js 22 breaking change but was mistakenly released as a patch version. It should have been a major release. This was corrected in `v11.0.0`. Do not upgrade directly from `v10.1.6` to `v10.1.7` without verifying Node.js version.","severity":"breaking","affected_versions":"10.1.7"},{"fix":"Use ESM `import` statements (e.g., `import { createClients } from 'contentful-batch-libs';`) in an environment configured for ESM (e.g., `\"type\": \"module\"` in `package.json` for Node.js projects).","message":"This library is primarily designed for ESM (ECMAScript Module) usage, especially from v11 onwards, aligning with modern Node.js practices. Attempting to `require()` it in a CommonJS context without proper transpilation or configuration can lead to import errors.","severity":"gotcha","affected_versions":">=11.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Convert 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.","cause":"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.","error":"ERR_REQUIRE_ESM: require() of ES Module ... from ... not supported."},{"fix":"Upgrade 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`.","cause":"Running `contentful-batch-libs` on a Node.js version older than the minimum required version (Node.js 22+ since v11.0.0).","error":"Error: Node.js vX.Y.Z is not supported. Please upgrade to Node.js >=22."}],"ecosystem":"npm"}