microcms-js-sdk

microCMS JavaScript SDK

It helps you to use microCMS from JavaScript and Node.js applications.

Tutorial

See the official tutorial.

Getting started

Installation

Node.js

$ npm install microcms-js-sdk

or

$ yarn add microcms-js-sdk

[!IMPORTANT] v3.0.0 or later requires Node.js v18 or higher.

Browser（Self-hosting）

Download and unzip microcms-js-sdk-x.y.z.tgz from the releases page. Then, host it on any server of your choice and use it. The target file is ./dist/umd/microcms-js-sdk.js.

<script src="./microcms-js-sdk.js"></script>

Browser（CDN）

Please load and use the URL provided by an external provider.

<script src="https://cdn.jsdelivr.net/npm/microcms-js-sdk@3.1.1/dist/umd/microcms-js-sdk.min.js"></script>

or

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

[!WARNING] The hosting service (cdn.jsdelivr.net) is not related to microCMS. For production use, we recommend self-hosting on your own server.

Contents API

Import

Node.js

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

or

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

Usage with a browser

<script>
  const { createClient } = microcms;
</script>

Create client object

// Initialize Client SDK.
const client = createClient({
  serviceDomain: 'YOUR_DOMAIN', // YOUR_DOMAIN is the XXXX part of XXXX.microcms.io
  apiKey: 'YOUR_API_KEY',
  // retry: true // Retry attempts up to a maximum of two times.
});

API methods

The 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 ✔️.

Method	List Format	Object Format
getList	✔️
getListDetail	✔️
getObject		✔️
getAllContentIds	✔️
getAllContents	✔️
create	✔️
update	✔️	✔️
delete	✔️

[!NOTE]

• ✔️ in "List Format" indicates the method can be used when the API type is set to List Format.
• ✔️ in "Object Format" indicates the method can be used when the API type is set to Object Format.

Get content list

The getList method is used to retrieve a list of content from a specified endpoint.

client
  .getList({
    endpoint: 'endpoint',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

Get content list with parameters

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

client
  .getList({
    endpoint: 'endpoint',
    queries: {
      draftKey: 'abcd',
      limit: 100,
      offset: 1,
      orders: 'createdAt',
      q: 'Hello',
      fields: 'id,title',
      ids: 'foo',
      filters: 'publishedAt[greater_than]2021-01-01T03:00:00.000Z',
      depth: 1,
    }
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

Get single content

The getListDetail method is used to retrieve a single content specified by its ID.

client
  .getListDetail({
    endpoint: 'endpoint',
    contentId: 'contentId',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

Get single content with parameters

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

client
  .getListDetail({
    endpoint: 'endpoint',
    contentId: 'contentId',
    queries: {
      draftKey: 'abcd',
      fields: 'id,title',
      depth: 1,
    }
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

Get object format content

The getObject method is used to retrieve a single object format content

client
  .getObject({
    endpoint: 'endpoint',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

Get all contentIds

The getAllContentIds method is used to retrieve all content IDs only.

client
  .getAllContentIds({
    endpoint: 'endpoint',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

Get all contentIds with filters

It is possible to retrieve only the content IDs for a specific category by specifying the filters.

client
  .getAllContentIds({
    endpoint: 'endpoint',
    filters: 'category[equals]uN28Folyn',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

Get all contentIds with draftKey

It is possible to include content from a specific draft by specifying the draftKey.

client
  .getAllContentIds({
    endpoint: 'endpoint',
    draftKey: 'draftKey',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

Get all contentIds with alternateField

The alternateField property can be used to address cases where the value of a field other than content ID is used in a URL, etc.

client
  .getAllContentIds({
    endpoint: 'endpoint',
    alternateField: 'url',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

Get all contents

The getAllContents method is used to retrieve all content data.

client
  .getAllContents({
    endpoint: 'endpoint',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

Get all contents with parameters

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

client
  .getAllContents({
    endpoint: 'endpoint',
    queries: { filters: 'createdAt[greater_than]2021-01-01T03:00:00.000Z', orders: '-createdAt' },
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

Create content

The create method is used to register content.

client
  .create({
    endpoint: 'endpoint',
    content: {
      title: 'title',
      body: 'body',
    },
  })
  .then((res) => console.log(res.id))
  .catch((err) => console.error(err));

Create content with specified ID

By specifying the contentId property, it is possible to register content with a specified ID.

client
  .create({
    endpoint: 'endpoint',
    contentId: 'contentId',
    content: {
      title: 'title',
      body: 'body',
    },
  })
  .then((res) => console.log(res.id))
  .catch((err) => console.error(err));

Create draft content

By specifying the isDraft property, it is possible to register the content as a draft.

client
  .create({
    endpoint: 'endpoint',
    content: {
      title: 'title',
      body: 'body',
    },
    // Available with microCMS paid plans
    // https://microcms.io/pricing
    isDraft: true,
  })
  .then((res) => console.log(res.id))
  .catch((err) => console.error(err));

Create draft content with specified ID

By specifying the contentId and isDraft properties, it is possible to register the content as a draft with a specified ID.

client
  .create({
    endpoint: 'endpoint',
    contentId: 'contentId',
    content: {
      title: 'title',
      body: 'body',
    },
    // Available with microCMS paid plans
    // https://microcms.io/pricing
    isDraft: true,
  })
  .then((res) => console.log(res.id))
  .catch((err) => console.error(err));

Update content

The update method is used to update a single content specified by its ID.

client
  .update({
    endpoint: 'endpoint',
    contentId: 'contentId',
    content: {
      title: 'title',
    },
  })
  .then((res) => console.log(res.id))
  .catch((err) => console.error(err));

Update object format content

When updating object content, use the update method without specifying a contentId property.

client
  .update({
    endpoint: 'endpoint',
    content: {
      title: 'title',
    },
  })
  .then((res) => console.log(res.id))
  .catch((err) => console.error(err));

Delete content

The delete method is used to delete a single content specified by its ID.

client
  .delete({
    endpoint: 'endpoint',
    contentId: 'contentId',
  })
  .catch((err) => console.error(err));

TypeScript

If you are using TypeScript, use getList, getListDetail, getObject. This internally contains a common type of content.

Response type for getList method

type Content = {
  text: string,
};
/**
 * {
 *  contents: Content[]; // This is array type of Content
 *  totalCount: number;
 *  limit: number;
 *  offset: number;
 * }
 */
client.getList<Content>({ /* other */ })

Response type for getListDetail method

type Content = {
  text: string,
};
/**
 * {
 *  id: string;
 *  createdAt: string;
 *  updatedAt: string;
 *  publishedAt?: string;
 *  revisedAt?: string;
 *  text: string; // This is Content type.
 * }
 */
client.getListDetail<Content>({ /* other */ })

Response type for getObject method

type Content = {
  text: string,
};
/**
 * {
 *  createdAt: string;
 *  updatedAt: string;
 *  publishedAt?: string;
 *  revisedAt?: string;
 *  text: string; // This is Content type.
 * }
 */

client.getObject<Content>({ /* other */ })

Response type for getAllContentIds method

/**
 * string[] // This is array type of string
 */
client.getAllContentIds({ /* other */ })

Create method with type safety

Since content will be of type Content, no required fields will be missed.

type Content = {
  title: string;
  body?: string;
};

client.create<Content>({
  endpoint: 'endpoint',
  content: {
    title: 'title',
    body: 'body',
  },
});

Update method with type safety

The content will be of type Partial<Content>, so you can enter only the items needed for the update.

type Content = {
  title: string;
  body?: string;
};

client.update<Content>({
  endpoint: 'endpoint',
  content: {
    body: 'body',
  },
});

CustomRequestInit

Next.js App Router

You can now use the fetch option of the Next.js App Router as CustomRequestInit. Please refer to the official Next.js documentation as the available options depend on the Next.js Type file.

Functions: fetch | Next.js

const response = await client.getList({
  customRequestInit: {
    next: {
      revalidate: 60,
    },
  },
  endpoint: 'endpoint',
});

AbortController: abort() method

You can abort fetch requests.

const controller = new AbortController();
const response = await client.getObject({
  customRequestInit: {
    signal: controller.signal,
  },
  endpoint: 'config',
});

setTimeout(() => {
  controller.abort();
}, 1000);

Management API

Import

Node.js

const { createManagementClient } = require('microcms-js-sdk'); // CommonJS

or

import { createManagementClient } from 'microcms-js-sdk'; //ES6

Usage with a browser

<script>
  const { createManagementClient } = microcms;
</script>

Create client object

const client = createManagementClient({
  serviceDomain: 'YOUR_DOMAIN', // YOUR_DOMAIN is the XXXX part of XXXX.microcms.io
  apiKey: 'YOUR_API_KEY',
});

Upload media

Media files can be uploaded using the 'POST /api/v1/media' endpoint of the Management API.

Node.js

// Blob
import { readFileSync } from 'fs';

const file = readFileSync('path/to/file');
client
  .uploadMedia({
    data: new Blob([file], { type: 'image/png' }),
    name: 'image.png',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

// or ReadableStream
import { createReadStream } from 'fs';
import { Stream } from 'stream';

const file = createReadStream('path/to/file');
client
  .uploadMedia({
    data: Stream.Readable.toWeb(file),
    name: 'image.png',
    type: 'image/png',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

// or URL
client
  .uploadMedia({
    data: 'https://example.com/image.png',
    // name: 'image.png', ← Optional
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

Browser

// File
const file = document.querySelector('input[type="file"]').files[0];
client
  .uploadMedia({
    data: file,
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

// or URL
client
  .uploadMedia({
    data: 'https://example.com/image.png',
    // name: 'image.png', ← Optional
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

TypeScript

Parameter type for uploadMedia method

type UploadMediaRequest =
  | { data: File }
  | { data: Blob; name: string }
  | { data: ReadableStream; name: string; type: `image/${string}` }
  | {
      data: URL | string;
      name?: string | null | undefined;
      customRequestHeaders?: HeadersInit;
    };
function uploadMedia(params: UploadMediaRequest): Promise<{ url: string }>;

Tips

Separate API keys for read and write

const readClient = createClient({
  serviceDomain: 'serviceDomain',
  apiKey: 'readApiKey',
});
const writeClient = createClient({
  serviceDomain: 'serviceDomain',
  apiKey: 'writeApiKey',
});

LICENSE

Apache-2.0