Registry / http-networking / microcms-js-sdk

microcms-js-sdk

library3.4.0jsnpmunverified

The `microcms-js-sdk` is the official JavaScript SDK client designed to interact with microCMS Content APIs and Management APIs from both Node.js and browser environments. Currently at stable version `3.4.0`, it receives regular updates, with several minor and patch releases in recent months, alongside a significant major update to v3.0.0. Key differentiators include its comprehensive support for microCMS's List and Object API formats, methods for common operations like content retrieval (`getList`, `getListDetail`, `getObject`), content creation, updating, and deletion. It also offers features like `getAllContents` and `getAllContentIds` for advanced retrieval patterns and a Management API client for tasks such as image uploads (introduced in v3.1.0). The SDK is type-safe as it ships with TypeScript definitions, making it suitable for modern JavaScript and TypeScript projects. Users should be aware of the breaking changes introduced in v3.0.0, particularly the shift to `global fetch` and a Node.js v18+ runtime requirement.

http-networking

npm install microcms-js-sdk

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MICROCMS-JS-SDK

microcms-js-sdk

http-networkingjavascriptv3.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createClient

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

✗ const { createClient } = require('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

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

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

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.

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();

Debug

Known issues

breakingVersion 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.

affects: >=3.0.0

breakingAs 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.

affects: >=3.0.0

breakingThe `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.

affects: >=3.0.0

securityVersion 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`.

affects: <3.4.0

gotchaWhen 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.

affects: All

Errors

Common errors & fixes

ReferenceError: fetch is not defined

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

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')

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'`.

Upgrade

Version history

3.4.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

54 hits · last 30 days

node

Resources

githubhttps://github.com/microcmsio/microcms-js-sdk ↗

packagehttps://www.npmjs.com/package/microcms-js-sdk ↗

homepagehttps://microcms.io ↗