{"id":11306,"library":"microcms-js-sdk","title":"microCMS JavaScript SDK","description":"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.","status":"active","version":"3.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/microcmsio/microcms-js-sdk","tags":["javascript","JavaScript","node","SDK","microCMS","typescript"],"install":[{"cmd":"npm install microcms-js-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add microcms-js-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add microcms-js-sdk","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { createClient } = require('microcms-js-sdk');","symbol":"createClient","correct":"import { createClient } from 'microcms-js-sdk';"},{"note":"This CommonJS `require` syntax is compatible with older Node.js projects. For new projects or those using ESM, the `import` statement is recommended.","symbol":"createClient","correct":"const { createClient } = require('microcms-js-sdk');"},{"note":"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.","wrong":"import { createClient } from 'microcms-js-sdk';","symbol":"microcms global object","correct":"<script src=\"https://cdn.jsdelivr.net/npm/microcms-js-sdk/dist/umd/microcms-js-sdk.min.js\"></script>\n<script>\n  const { createClient } = microcms;\n</script>"}],"quickstart":{"code":"import { createClient } from 'microcms-js-sdk';\n\ninterface MyContent {\n  id: string;\n  title: string;\n  description: string;\n  createdAt: string;\n  updatedAt: string;\n  publishedAt: string;\n  revisedAt: string;\n}\n\nconst client = createClient({\n  serviceDomain: process.env.MICROCMS_SERVICE_DOMAIN ?? 'YOUR_SERVICE_DOMAIN',\n  apiKey: process.env.MICROCMS_API_KEY ?? 'YOUR_API_KEY',\n});\n\nasync function fetchContentList() {\n  try {\n    const response = await client.getList<MyContent>({\n      endpoint: 'blogs',\n      queries: {\n        limit: 5,\n        offset: 0,\n        orders: '-publishedAt',\n        fields: 'id,title,publishedAt',\n        filters: 'publishedAt[less_than]2026-12-31T23:59:59.999Z'\n      }\n    });\n    console.log('Fetched content list:', JSON.stringify(response, null, 2));\n    return response;\n  } catch (error) {\n    console.error('Error fetching content:', error);\n    throw error;\n  }\n}\n\nfetchContentList();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update `microcms-js-sdk` to version `3.4.0` or later using `npm update microcms-js-sdk` or `yarn upgrade microcms-js-sdk`.","message":"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.","severity":"security","affected_versions":"<3.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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+.","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.","error":"ReferenceError: fetch is not defined"},{"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.","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.","error":"TypeError: client.getList is not a function"},{"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'`.","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.","error":"TypeError: Cannot read properties of undefined (reading 'serviceDomain')"}],"ecosystem":"npm"}