microCMS JavaScript SDK

Common errors

• ReferenceError: fetch is not defined

  cause Attempting to use `microcms-js-sdk` v3.0.0 or later in a Node.js environment older than v18, which does not natively provide the `fetch` API.
  fix Upgrade your Node.js version to 18.0.0 or higher. Alternatively, if upgrading is not immediately possible, you may need to explicitly polyfill `fetch` globally in your application's entry point, though this is not officially supported by the SDK maintainers for v3+.

• TypeError: client.getList is not a function

  cause This error often occurs when `createClient` is not properly imported or initialized, or when the `client` object is not correctly instantiated before attempting to call its methods. This can happen with incorrect CommonJS `require` syntax in an ESM module, or a failed global script load in a browser.
  fix Verify that `createClient` is imported correctly based on your module system (ESM `import` for modern Node.js/bundlers, CommonJS `require` for older Node.js, or `microcms.createClient` for browser UMD). Ensure `createClient` is called and its result is assigned to a variable (`client`) before attempting to use `client.getList` or other methods.

• TypeError: Cannot read properties of undefined (reading 'serviceDomain')

  cause The configuration object passed to `createClient` is missing `serviceDomain` or `apiKey`, or these properties are `undefined` due to incorrect environment variable loading or typos.
  fix Ensure that `serviceDomain` and `apiKey` are correctly provided as strings when initializing the client. Double-check environment variable names and fallback values. For example: `serviceDomain: process.env.MICROCMS_SERVICE_DOMAIN || 'your_domain'`.

Warnings

• breaking Version 3.0.0 introduced significant breaking changes, primarily the removal of `cross-fetch` and the `customFetch` option. The SDK now relies entirely on the native `global fetch` API. Projects that previously used `customFetch` for polyfills or custom HTTP clients must adjust.
  Fix: Ensure your environment (Node.js >=18 or modern browser) supports the native `fetch` API. Remove any usage of the `customFetch` option or `cross-fetch` polyfills managed by the SDK. If `fetch` is not globally available in your Node.js environment, consider a dedicated polyfill at your application's entry point.
• breaking As of v3.0.0, the minimum supported Node.js version has been elevated to v18.0.0 or higher. Older Node.js runtimes will not be able to run this SDK version due to its reliance on native `fetch` and `URLSearchParams` without polyfills.
  Fix: Upgrade your Node.js runtime to version 18.0.0 or newer. Check your `package.json` engines field and CI/CD environments to ensure compatibility.
• breaking The `qs` package, previously used for query parameter serialization, was removed in v3.0.0. The SDK now exclusively uses `URLSearchParams()` for query string handling. While this should be largely transparent for standard usage, custom or complex query parameter structures might behave differently.
  Fix: No direct code changes are typically required unless you were relying on specific `qs` serialization quirks. Ensure all query parameters adhere to `URLSearchParams` compatibility, especially for array or nested object serialization.
• security Version 3.4.0 included security releases labeled 'march-2026-security-releases'. Users should update to the latest patch version to ensure all recent security patches are applied.
  Fix: Update `microcms-js-sdk` to version `3.4.0` or later using `npm update microcms-js-sdk` or `yarn upgrade microcms-js-sdk`.
• gotcha When using the SDK via CDN (e.g., `cdn.jsdelivr.net`), a warning is explicitly provided that the hosting service is not related to microCMS. For production environments, self-hosting the UMD bundle is recommended to ensure stability and control over asset delivery.
  Fix: For production applications, download the `microcms-js-sdk.js` UMD bundle from the GitHub releases page and host it on your own server or content delivery network instead of relying on third-party CDNs.

Install

• npm install microcms-js-sdk npm
• yarn add microcms-js-sdk yarn
• pnpm add microcms-js-sdk pnpm

Imports

• createClient
  wrong:

  const { createClient } = require('microcms-js-sdk');

  correct:

  import { createClient } from 'microcms-js-sdk';

  ESM import is the modern and recommended way since v3.0.0, especially for Node.js environments. The CommonJS `require` syntax is still supported but ESM is preferred in newer projects.
• createClient

  const { createClient } = require('microcms-js-sdk');

  This CommonJS `require` syntax is compatible with older Node.js projects. For new projects or those using ESM, the `import` statement is recommended.
• microcms global object
  wrong:

  import { createClient } from 'microcms-js-sdk';

  correct:

  <script src="https://cdn.jsdelivr.net/npm/microcms-js-sdk/dist/umd/microcms-js-sdk.min.js"></script>
  <script>
    const { createClient } = microcms;
  </script>

  When using the SDK directly in a browser via a UMD build (e.g., from a CDN or self-hosted file), the `createClient` function is exposed under the global `microcms` object. Direct ESM/CJS imports are for bundlers or Node.js.

Quickstart

This quickstart initializes the microCMS client and fetches a paginated list of blog content, demonstrating querying with filters and field selection. It includes basic TypeScript typing for the content structure.

import { createClient } from 'microcms-js-sdk';

interface MyContent {
  id: string;
  title: string;
  description: string;
  createdAt: string;
  updatedAt: string;
  publishedAt: string;
  revisedAt: string;
}

const client = createClient({
  serviceDomain: process.env.MICROCMS_SERVICE_DOMAIN ?? 'YOUR_SERVICE_DOMAIN',
  apiKey: process.env.MICROCMS_API_KEY ?? 'YOUR_API_KEY',
});

async function fetchContentList() {
  try {
    const response = await client.getList<MyContent>({
      endpoint: 'blogs',
      queries: {
        limit: 5,
        offset: 0,
        orders: '-publishedAt',
        fields: 'id,title,publishedAt',
        filters: 'publishedAt[less_than]2026-12-31T23:59:59.999Z'
      }
    });
    console.log('Fetched content list:', JSON.stringify(response, null, 2));
    return response;
  } catch (error) {
    console.error('Error fetching content:', error);
    throw error;
  }
}

fetchContentList();