{"id":19900653,"url":"https://github.com/microcmsio/microcms-js-sdk","last_synced_at":"2025-05-15T11:06:10.831Z","repository":{"id":43533724,"uuid":"358441339","full_name":"microcmsio/microcms-js-sdk","owner":"microcmsio","description":"microCMS JavaScript SDK.","archived":false,"fork":false,"pushed_at":"2025-03-14T02:26:49.000Z","size":694,"stargazers_count":171,"open_issues_count":10,"forks_count":30,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-05-08T04:16:09.734Z","etag":null,"topics":["javascript","microcms","nodejs"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/microcms-js-sdk","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/microcmsio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-16T01:33:45.000Z","updated_at":"2025-04-03T23:39:56.000Z","dependencies_parsed_at":"2023-02-18T04:31:25.341Z","dependency_job_id":"14602d35-1981-49c1-b281-32af22c93501","html_url":"https://github.com/microcmsio/microcms-js-sdk","commit_stats":{"total_commits":83,"total_committers":12,"mean_commits":6.916666666666667,"dds":0.4819277108433735,"last_synced_commit":"acc4263ba7bec8d98ce9af665863161beecae38d"},"previous_names":["wantainc/microcms-js-sdk"],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microcmsio%2Fmicrocms-js-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microcmsio%2Fmicrocms-js-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microcmsio%2Fmicrocms-js-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microcmsio%2Fmicrocms-js-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microcmsio","download_url":"https://codeload.github.com/microcmsio/microcms-js-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254328385,"owners_count":22052632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","microcms","nodejs"],"created_at":"2024-11-12T20:12:52.147Z","updated_at":"2025-05-15T11:06:10.812Z","avatar_url":"https://github.com/microcmsio.png","language":"TypeScript","readme":"# microCMS JavaScript SDK\n\n[日本語版 README](README_jp.md)\n\nIt helps you to use microCMS from JavaScript and Node.js applications.\n\n\u003ca href=\"https://discord.com/invite/K3DPqw4EJ2\" target=\"_blank\"\u003e\u003cimg src=\"https://img.shields.io/badge/Discord-%235865F2.svg?style=for-the-badge\u0026logo=discord\u0026logoColor=white\" alt=\"Discord\"\u003e\u003c/a\u003e\n\n## Tutorial\n\nSee the [official tutorial](https://document.microcms.io/tutorial/javascript/javascript-top).\n\n## Getting started\n\n### Installation\n\n#### Node.js\n\n```bash\n$ npm install microcms-js-sdk\n\nor\n\n$ yarn add microcms-js-sdk\n```\n\n\u003e [!IMPORTANT]\n\u003e v3.0.0 or later requires Node.js **v18 or higher**.\n\n#### Browser（Self-hosting）\n\nDownload and unzip `microcms-js-sdk-x.y.z.tgz` from the [releases page](https://github.com/microcmsio/microcms-js-sdk/releases). Then, host it on any server of your choice and use it. The target file is `./dist/umd/microcms-js-sdk.js`.\n\n```html\n\u003cscript src=\"./microcms-js-sdk.js\"\u003e\u003c/script\u003e\n```\n\n#### Browser（CDN）\n\nPlease load and use the URL provided by an external provider.\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/microcms-js-sdk@3.1.1/dist/umd/microcms-js-sdk.min.js\"\u003e\u003c/script\u003e\n```\n\nor\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/microcms-js-sdk/dist/umd/microcms-js-sdk.min.js\"\u003e\u003c/script\u003e\n```\n\n\u003e [!WARNING]\n\u003e The hosting service (cdn.jsdelivr.net) is not related to microCMS. For production use, we recommend self-hosting on your own server.\n\n## Contents API\n\n### Import\n\n#### Node.js\n\n```javascript\nconst { createClient } = require('microcms-js-sdk'); // CommonJS\n```\n\nor\n\n```javascript\nimport { createClient } from 'microcms-js-sdk'; //ES6\n```\n\n#### Usage with a browser\n\n```html\n\u003cscript\u003e\n  const { createClient } = microcms;\n\u003c/script\u003e\n```\n\n### Create client object\n\n```javascript\n// Initialize Client SDK.\nconst client = createClient({\n  serviceDomain: 'YOUR_DOMAIN', // YOUR_DOMAIN is the XXXX part of XXXX.microcms.io\n  apiKey: 'YOUR_API_KEY',\n  // retry: true // Retry attempts up to a maximum of two times.\n});\n```\n\n### API methods\n\nThe table below shows each API method of microCMS JavaScript SDK and indicates which API format (List Format or Object Format) they can be used with using ✔️.\n\n| Method            | List Format | Object Format |\n|-------------------|-------------|---------------|\n| getList           | ✔️          |               |\n| getListDetail     | ✔️          |               |\n| getObject         |            | ✔️             |\n| getAllContentIds  | ✔️          |               |\n| getAllContents    | ✔️          |               |\n| create            | ✔️          |               |\n| update            | ✔️          | ✔️             |\n| delete            | ✔️          |               |\n\n\u003e [!NOTE]\n\u003e - ✔️ in \"List Format\" indicates the method can be used when the API type is set to List Format.\n\u003e - ✔️ in \"Object Format\" indicates the method can be used when the API type is set to Object Format.\n\n### Get content list\n\nThe `getList` method is used to retrieve a list of content from a specified endpoint.\n\n```javascript\nclient\n  .getList({\n    endpoint: 'endpoint',\n  })\n  .then((res) =\u003e console.log(res))\n  .catch((err) =\u003e console.error(err));\n```\n\n#### Get content list with parameters\n\nThe `queries` property can be used to specify parameters for retrieving content that matches specific criteria. For more details on each available property, refer to the [microCMS Documentation](https://document.microcms.io/content-api/get-list-contents#h929d25d495).\n\n```javascript\nclient\n  .getList({\n    endpoint: 'endpoint',\n    queries: {\n      draftKey: 'abcd',\n      limit: 100,\n      offset: 1,\n      orders: 'createdAt',\n      q: 'Hello',\n      fields: 'id,title',\n      ids: 'foo',\n      filters: 'publishedAt[greater_than]2021-01-01T03:00:00.000Z',\n      depth: 1,\n    }\n  })\n  .then((res) =\u003e console.log(res))\n  .catch((err) =\u003e console.error(err));\n```\n\n### Get single content\n\nThe `getListDetail` method is used to retrieve a single content specified by its ID.\n\n```javascript\nclient\n  .getListDetail({\n    endpoint: 'endpoint',\n    contentId: 'contentId',\n  })\n  .then((res) =\u003e console.log(res))\n  .catch((err) =\u003e console.error(err));\n```\n\n#### Get single content with parameters\n\nThe `queries` property can be used to specify parameters for retrieving a single content that matches specific criteria. For more details on each available property, refer to the [microCMS Documentation](https://document.microcms.io/content-api/get-content#h929d25d495).\n\n```javascript\nclient\n  .getListDetail({\n    endpoint: 'endpoint',\n    contentId: 'contentId',\n    queries: {\n      draftKey: 'abcd',\n      fields: 'id,title',\n      depth: 1,\n    }\n  })\n  .then((res) =\u003e console.log(res))\n  .catch((err) =\u003e console.error(err));\n\n```\n\n### Get object format content\n\nThe `getObject` method is used to retrieve a single object format content\n\n```javascript\nclient\n  .getObject({\n    endpoint: 'endpoint',\n  })\n  .then((res) =\u003e console.log(res))\n  .catch((err) =\u003e console.error(err));\n```\n\n### Get all contentIds\n\nThe `getAllContentIds` method is used to retrieve all content IDs only.  \n\n```javascript\nclient\n  .getAllContentIds({\n    endpoint: 'endpoint',\n  })\n  .then((res) =\u003e console.log(res))\n  .catch((err) =\u003e console.error(err));\n```\n\n#### Get all contentIds with filters\n\nIt is possible to retrieve only the content IDs for a specific category by specifying the `filters`.\n\n```javascript\nclient\n  .getAllContentIds({\n    endpoint: 'endpoint',\n    filters: 'category[equals]uN28Folyn',\n  })\n  .then((res) =\u003e console.log(res))\n  .catch((err) =\u003e console.error(err));\n```\n\n#### Get all contentIds with draftKey\n\nIt is possible to include content from a specific draft by specifying the `draftKey`.\n\n```javascript\nclient\n  .getAllContentIds({\n    endpoint: 'endpoint',\n    draftKey: 'draftKey',\n  })\n  .then((res) =\u003e console.log(res))\n  .catch((err) =\u003e console.error(err));\n```\n\n#### Get all contentIds with alternateField\n\nThe `alternateField` property can be used to address cases where the value of a field other than content ID is used in a URL, etc.\n\n```javascript\nclient\n  .getAllContentIds({\n    endpoint: 'endpoint',\n    alternateField: 'url',\n  })\n  .then((res) =\u003e console.log(res))\n  .catch((err) =\u003e console.error(err));\n```\n\n### Get all contents\n\nThe `getAllContents` method is used to retrieve all content data.\n\n```javascript\nclient\n  .getAllContents({\n    endpoint: 'endpoint',\n  })\n  .then((res) =\u003e console.log(res))\n  .catch((err) =\u003e console.error(err));\n```\n\n#### Get all contents with parameters\n\nThe `queries` property can be used to specify parameters for retrieving all content that matches specific criteria. For more details on each available property, refer to the [microCMS Documentation](https://document.microcms.io/content-api/get-list-contents#h929d25d495).\n\n```javascript\nclient\n  .getAllContents({\n    endpoint: 'endpoint',\n    queries: { filters: 'createdAt[greater_than]2021-01-01T03:00:00.000Z', orders: '-createdAt' },\n  })\n  .then((res) =\u003e console.log(res))\n  .catch((err) =\u003e console.error(err));\n```\n\n### Create content\n\nThe `create` method is used to register content.\n\n```javascript\nclient\n  .create({\n    endpoint: 'endpoint',\n    content: {\n      title: 'title',\n      body: 'body',\n    },\n  })\n  .then((res) =\u003e console.log(res.id))\n  .catch((err) =\u003e console.error(err));\n```\n\n#### Create content with specified ID\n\nBy specifying the `contentId` property, it is possible to register content with a specified ID.\n\n```javascript\nclient\n  .create({\n    endpoint: 'endpoint',\n    contentId: 'contentId',\n    content: {\n      title: 'title',\n      body: 'body',\n    },\n  })\n  .then((res) =\u003e console.log(res.id))\n  .catch((err) =\u003e console.error(err));\n```\n\n#### Create draft content\n\nBy specifying the `isDraft` property, it is possible to register the content as a draft.\n\n```javascript\nclient\n  .create({\n    endpoint: 'endpoint',\n    content: {\n      title: 'title',\n      body: 'body',\n    },\n    // Available with microCMS paid plans\n    // https://microcms.io/pricing\n    isDraft: true,\n  })\n  .then((res) =\u003e console.log(res.id))\n  .catch((err) =\u003e console.error(err));\n```\n\n#### Create draft content with specified ID\n\nBy specifying the `contentId` and `isDraft` properties, it is possible to register the content as a draft with a specified ID.\n\n```javascript\nclient\n  .create({\n    endpoint: 'endpoint',\n    contentId: 'contentId',\n    content: {\n      title: 'title',\n      body: 'body',\n    },\n    // Available with microCMS paid plans\n    // https://microcms.io/pricing\n    isDraft: true,\n  })\n  .then((res) =\u003e console.log(res.id))\n  .catch((err) =\u003e console.error(err));\n```\n\n### Update content\n\nThe `update` method is used to update a single content specified by its ID.\n\n```javascript\nclient\n  .update({\n    endpoint: 'endpoint',\n    contentId: 'contentId',\n    content: {\n      title: 'title',\n    },\n  })\n  .then((res) =\u003e console.log(res.id))\n  .catch((err) =\u003e console.error(err));\n```\n\n#### Update object format content\n\nWhen updating object content, use the `update` method without specifying a `contentId` property.\n\n```javascript\nclient\n  .update({\n    endpoint: 'endpoint',\n    content: {\n      title: 'title',\n    },\n  })\n  .then((res) =\u003e console.log(res.id))\n  .catch((err) =\u003e console.error(err));\n```\n\n### Delete content\n\nThe `delete` method is used to delete a single content specified by its ID.\n\n```javascript\nclient\n  .delete({\n    endpoint: 'endpoint',\n    contentId: 'contentId',\n  })\n  .catch((err) =\u003e console.error(err));\n```\n\n### TypeScript\n\nIf you are using TypeScript, use `getList`, `getListDetail`, `getObject`. This internally contains a common type of content.\n\n#### Response type for getList method\n\n```typescript\ntype Content = {\n  text: string,\n};\n/**\n * {\n *  contents: Content[]; // This is array type of Content\n *  totalCount: number;\n *  limit: number;\n *  offset: number;\n * }\n */\nclient.getList\u003cContent\u003e({ /* other */ })\n```\n\n#### Response type for getListDetail method\n\n```typescript\ntype Content = {\n  text: string,\n};\n/**\n * {\n *  id: string;\n *  createdAt: string;\n *  updatedAt: string;\n *  publishedAt?: string;\n *  revisedAt?: string;\n *  text: string; // This is Content type.\n * }\n */\nclient.getListDetail\u003cContent\u003e({ /* other */ })\n```\n\n#### Response type for getObject method\n\n```typescript\ntype Content = {\n  text: string,\n};\n/**\n * {\n *  createdAt: string;\n *  updatedAt: string;\n *  publishedAt?: string;\n *  revisedAt?: string;\n *  text: string; // This is Content type.\n * }\n */\n\nclient.getObject\u003cContent\u003e({ /* other */ })\n```\n\n#### Response type for getAllContentIds method\n\n```typescript\n/**\n * string[] // This is array type of string\n */\nclient.getAllContentIds({ /* other */ })\n```\n\n#### Create method with type safety\n\nSince `content` will be of type `Content`, no required fields will be missed.\n\n```typescript\ntype Content = {\n  title: string;\n  body?: string;\n};\n\nclient.create\u003cContent\u003e({\n  endpoint: 'endpoint',\n  content: {\n    title: 'title',\n    body: 'body',\n  },\n});\n```\n\n#### Update method with type safety\n\n The `content` will be of type `Partial\u003cContent\u003e`, so you can enter only the items needed for the update.\n\n```typescript\ntype Content = {\n  title: string;\n  body?: string;\n};\n\nclient.update\u003cContent\u003e({\n  endpoint: 'endpoint',\n  content: {\n    body: 'body',\n  },\n});\n```\n\n### CustomRequestInit\n\n#### Next.js App Router\n\nYou can now use the fetch option of the Next.js App Router as CustomRequestInit.\nPlease refer to the official Next.js documentation as the available options depend on the Next.js Type file.\n\n[Functions: fetch \\| Next\\.js](https://nextjs.org/docs/app/api-reference/functions/fetch)\n\n```ts\nconst response = await client.getList({\n  customRequestInit: {\n    next: {\n      revalidate: 60,\n    },\n  },\n  endpoint: 'endpoint',\n});\n```\n\n#### AbortController: abort() method\n\nYou can abort fetch requests.\n\n```ts\nconst controller = new AbortController();\nconst response = await client.getObject({\n  customRequestInit: {\n    signal: controller.signal,\n  },\n  endpoint: 'config',\n});\n\nsetTimeout(() =\u003e {\n  controller.abort();\n}, 1000);\n```\n\n## Management API\n\n### Import\n\n#### Node.js\n\n```javascript\nconst { createManagementClient } = require('microcms-js-sdk'); // CommonJS\n```\n\nor\n\n```javascript\nimport { createManagementClient } from 'microcms-js-sdk'; //ES6\n```\n\n#### Usage with a browser\n\n```html\n\u003cscript\u003e\n  const { createManagementClient } = microcms;\n\u003c/script\u003e\n```\n\n### Create client object\n\n```javascript\nconst client = createManagementClient({\n  serviceDomain: 'YOUR_DOMAIN', // YOUR_DOMAIN is the XXXX part of XXXX.microcms.io\n  apiKey: 'YOUR_API_KEY',\n});\n```\n\n### Upload media\n\nMedia files can be uploaded using the 'POST /api/v1/media' endpoint of the Management API.\n\n#### Node.js\n\n```javascript\n// Blob\nimport { readFileSync } from 'fs';\n\nconst file = readFileSync('path/to/file');\nclient\n  .uploadMedia({\n    data: new Blob([file], { type: 'image/png' }),\n    name: 'image.png',\n  })\n  .then((res) =\u003e console.log(res))\n  .catch((err) =\u003e console.error(err));\n\n// or ReadableStream\nimport { createReadStream } from 'fs';\nimport { Stream } from 'stream';\n\nconst file = createReadStream('path/to/file');\nclient\n  .uploadMedia({\n    data: Stream.Readable.toWeb(file),\n    name: 'image.png',\n    type: 'image/png',\n  })\n  .then((res) =\u003e console.log(res))\n  .catch((err) =\u003e console.error(err));\n\n// or URL\nclient\n  .uploadMedia({\n    data: 'https://example.com/image.png',\n    // name: 'image.png', ← Optional\n  })\n  .then((res) =\u003e console.log(res))\n  .catch((err) =\u003e console.error(err));\n```\n\n#### Browser\n\n```javascript\n// File\nconst file = document.querySelector('input[type=\"file\"]').files[0];\nclient\n  .uploadMedia({\n    data: file,\n  })\n  .then((res) =\u003e console.log(res))\n  .catch((err) =\u003e console.error(err));\n\n// or URL\nclient\n  .uploadMedia({\n    data: 'https://example.com/image.png',\n    // name: 'image.png', ← Optional\n  })\n  .then((res) =\u003e console.log(res))\n  .catch((err) =\u003e console.error(err));\n```\n\n### TypeScript\n\n#### Parameter type for uploadMedia method\n\n```typescript\ntype UploadMediaRequest =\n  | { data: File }\n  | { data: Blob; name: string }\n  | { data: ReadableStream; name: string; type: `image/${string}` }\n  | {\n      data: URL | string;\n      name?: string | null | undefined;\n      customRequestHeaders?: HeadersInit;\n    };\nfunction uploadMedia(params: UploadMediaRequest): Promise\u003c{ url: string }\u003e;\n```\n\n## Tips\n\n### Separate API keys for read and write\n\n```javascript\nconst readClient = createClient({\n  serviceDomain: 'serviceDomain',\n  apiKey: 'readApiKey',\n});\nconst writeClient = createClient({\n  serviceDomain: 'serviceDomain',\n  apiKey: 'writeApiKey',\n});\n```\n\n## LICENSE\n\nApache-2.0\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrocmsio%2Fmicrocms-js-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrocmsio%2Fmicrocms-js-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrocmsio%2Fmicrocms-js-sdk/lists"}