Required dependencies

npm install @contentful/rich-text-types axios contentful-sdk-core fast-copy globals process

No native build steps, CocoaPods, or Android linking are required. This is a pure JavaScript/TypeScript library compatible with Node.js LTS and modern browsers.

Project setup

1. Copy the source/ directory into your project, e.g. src/contentful-management/.
2. In tsconfig.json add a path alias so imports resolve cleanly:

   {
     "compilerOptions": {
       "paths": {
         "contentful-management": ["./src/contentful-management/index.ts"],
         "contentful-management/*": ["./src/contentful-management/*"]
       }
     }
   }
   

3. Ensure "moduleResolution": "bundler" or "node16" / "nodenext" is set; the source uses export type * which requires TypeScript ≥ 5.0.
4. Set your access token via environment variable:

   export CONTENTFUL_MANAGEMENT_TOKEN=your_personal_access_token
   

5. If you bundle for the browser, alias process and globals via your bundler (Vite, webpack, etc.) since the source imports them explicitly.

Public API

createClient

import { createClient } from './src/contentful-management/index'
import type { ClientOptions } from './src/contentful-management/index'

// Overload 1 – returns PlainClientAPI when defaultParams supplied
export function createClient(clientOptions: ClientOptions): PlainClientAPI

// Overload 2 – returns chained ClientAPI
export function createClient(clientOptions: ClientOptions, opts?: { type: 'plain' }): ClientAPI

The primary factory. Pass { accessToken } (and optionally application, integration, feature for user-agent tagging) to receive a fully initialised client. Use the PlainClientAPI variant when you want flat, tree-shakeable calls; use ClientAPI when you prefer chaining (space.getEnvironment(...).getEntry(...)).

PlainClientAPI (type)

import type { PlainClientAPI } from './src/contentful-management/index'

A flat interface where every CMA operation is a direct async method, e.g. client.entry.get(params), client.asset.publish(params). Prefer this in serverless functions and large applications where bundle size matters. Exported from plain/plain-client-types.ts.

fetchAll

import { fetchAll } from './src/contentful-management/index'

async function fetchAll<T>(
  fn: (params: { skip: number; limit: number }) => Promise<{ items: T[]; total: number }>,
  params?: Record<string, unknown>
): Promise<T[]>

Automatically paginates through a collection endpoint and resolves with all items concatenated. Use whenever you need every record from a large collection without manual loop management.

editorInterfaceDefaults

import { editorInterfaceDefaults } from './src/contentful-management/index'

editorInterfaceDefaults.SidebarEntryConfiguration
editorInterfaceDefaults.SidebarAssetConfiguration
editorInterfaceDefaults.EntryConfiguration
editorInterfaceDefaults.getDefaultControlOfField(field)

Static defaults for constructing editor interfaces programmatically. Use when bootstrapping a new content type and you want to apply Contentful's built-in widget assignments without hardcoding them.

ScheduledActionStatus

import { ScheduledActionStatus } from './src/contentful-management/index'
// Enum values: 'scheduled' | 'inProgress' | 'succeeded' | 'failed' | 'canceled'

Enum for filtering or asserting on the status field of scheduled action entities.

Working examples

Scenario - Create and publish an entry

A backend migration script creates a new entry in a given content type and immediately publishes it.

import { createClient } from './src/contentful-management/index'

const client = createClient({
  accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN!,
})

async function createAndPublishEntry() {
  const space = await client.getSpace('mySpaceId')
  const env = await space.getEnvironment('master')

  const entry = await env.createEntry('article', {
    fields: {
      title: { 'en-US': 'Hello World' },
      body: { 'en-US': 'First programmatic entry.' },
    },
  })

  const published = await entry.publish()
  console.log('Published entry id:', published.sys.id)
}

createAndPublishEntry()

Scenario - Paginate all assets using PlainClientAPI and fetchAll

Retrieve every asset in an environment using the flat client and the fetchAll helper.

import { createClient, fetchAll } from './src/contentful-management/index'
import type { PlainClientDefaultParams } from './src/contentful-management/index'

const defaultParams: PlainClientDefaultParams = {
  spaceId: 'mySpaceId',
  environmentId: 'master',
}

const client = createClient(
  { accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN! },
  { type: 'plain' }
)

async function getAllAssets() {
  const assets = await fetchAll((params) =>
    client.asset.getMany({ ...defaultParams, query: params })
  )
  console.log(`Total assets: ${assets.length}`)
}

getAllAssets()

Scenario - Apply default editor interface controls to a new content type

Use editorInterfaceDefaults.getDefaultControlOfField to wire default widgets after creating a content type.

import { createClient, editorInterfaceDefaults } from './src/contentful-management/index'

const client = createClient({
  accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN!,
})

async function setupContentType() {
  const space = await client.getSpace('mySpaceId')
  const env = await space.getEnvironment('master')

  const ct = await env.createContentType({
    name: 'Blog Post',
    fields: [
      { id: 'title', name: 'Title', type: 'Symbol', required: true },
      { id: 'body', name: 'Body', type: 'Text', required: false },
    ],
  })

  await ct.publish()

  const ei = await ct.getEditorInterface()

  const controls = ct.fields.map((field) => ({
    fieldId: field.id,
    ...editorInterfaceDefaults.getDefaultControlOfField(field),
  }))

  ei.controls = controls
  await ei.update()
  console.log('Editor interface updated with default controls.')
}

setupContentType()

File walkthrough

• index.ts - Package entry: exports createClient, type re-exports, editorInterfaceDefaults, fetchAll, asIterator, ScheduledActionStatus, and RestAdapter.
• common-types.ts - Central hub for all prop and param interfaces shared across entities and adapter layers.
• common-utils.ts - Cursor-pagination normalisation helpers (normalizeCursorPaginationParameters, normalizeCursorPaginationResponse).
• create-adapter.ts - Reads AdapterParams and instantiates the appropriate transport adapter.
• create-contentful-api.ts - Assembles the chained ClientAPI object returned by createClient without type: 'plain'.
• create-entry-api.ts - Attaches all entry instance methods (publish, unpublish, delete, getReferences, etc.).
• create-environment-api.ts - Attaches all environment-scoped methods for assets, entries, content types, releases, bulk actions, and more.
• create-environment-template-api.ts - Methods specific to environment template management.
• create-organization-api.ts - Organisation-level resource methods (memberships, invitations, app definitions, etc.).
• create-space-api.ts - Space-level methods (environment CRUD, API keys, roles, webhooks, etc.).
• create-app-definition-api.ts - App definition instance methods.
• create-ui-config-api.ts / create-user-ui-config-api.ts - UI and per-user UI config methods.
• enhance-with-methods.ts - Generic mixin that grafts method sets onto raw entity response objects.
• export-types.ts - Barrel re-export of every entity type for consumer TypeScript projects.
• upload-http-client.ts - Separate axios instance configured for multipart/binary uploads.
• adapters/ - Adapter abstraction; REST/ contains the REST adapter, make-request.ts, and one file per endpoint group.
• constants/ - editorInterfaceDefaults with sidebar, editor, and control defaults.
• entities/ - Per-resource type definitions and wrap helpers converting raw API responses to SDK objects.
• methods/ - Reusable async method implementations shared by multiple API surface modules.
• plain/ - PlainClientAPI implementation, fetchAll, asIterator, isDraft/isPublished/isUpdated checks, wrapper utilities.

Common pitfalls and fixes

• Token not set at runtime: createClient throws an opaque axios 401 error; always validate process.env.CONTENTFUL_MANAGEMENT_TOKEN is defined before calling createClient.
• TypeScript < 5.0 rejects export type *: export-types.ts uses the export type * syntax; upgrade to TypeScript ≥ 5.0 or add "skipLibCheck": true as a temporary workaround.
• ESM/CJS interop with contentful-sdk-core: If your bundler emits CJS and contentful-sdk-core ships ESM-only, add it to esmExternals (Rollup/Vite) or use moduleNameMapper in Jest to point to the CJS dist.
• process is undefined in browser bundles: The source imports process from the process npm package; configure your bundler to provide or alias it (ProvidePlugin in webpack, define in Vite).
• Rate limiting: The CMA enforces request-per-second limits per API key; contentful-sdk-core adds automatic retry with back-off, but very tight loops can still exhaust the budget — use fetchAll instead of manual paginating loops.
• fast-copy peer version: If you see Cannot find module 'fast-copy', ensure you have installed the exact version range declared in package.json; mismatched hoisting in monorepos can silently skip it.

Vibe-coding prompt template

I have dropped the Contentful Management JS SDK source into `src/contentful-management/`
and I have a USAGE.md in the same directory that describes every export and contains
working TypeScript examples.

Upstream package: contentful-management (npm)
Source root: src/contentful-management/index.ts

Please help me integrate this into my project step-by-step:

1. Read USAGE.md and src/contentful-management/index.ts to understand the available exports.
2. Install the required runtime dependencies listed in USAGE.md under "Required dependencies".
3. Add the tsconfig paths alias exactly as shown in USAGE.md "Project setup".
4. Create a `src/cms-client.ts` module that exports a singleton PlainClientAPI instance
   using `createClient` with the accessToken read from the environment variable
   CONTENTFUL_MANAGEMENT_TOKEN.
5. Using that singleton, write a function `listAllEntries(spaceId, environmentId, contentType)`
   that returns all entries of a given content type using `fetchAll`.
6. Write a function `publishEntry(spaceId, environmentId, entryId)` using the plain client.
7. Add error handling that logs Contentful API errors (status code + message) without
   crashing the process.
8. Show me the final files and explain any assumption you made about my project structure.

License and credit

The upstream project is released under the MIT License (see source/LICENSE if present, or the GitHub repository). This block packages an unmodified copy of the library source. All credit goes to Contentful GmbH and the open-source contributors to contentful-management.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.

Sanity JavaScript Client for Content Lake

Automation, Utilities & Developer Tools

무료