microCMS JavaScript SDK
It helps you to use microCMS from JavaScript and Node.js applications.
Getting Started
Install
Node.js
Install npm package.
$ 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 (unpkg.com) is not related to microCMS. For production use, we recommend self-hosting on your own server.
How to use
First, create a client.
const { createClient } = require('microcms-js-sdk');
import { createClient } from 'microcms-js-sdk';
const client = createClient({
serviceDomain: 'YOUR_DOMAIN',
apiKey: 'YOUR_API_KEY',
});
When using with a browser.
<script>
const { createClient } = microcms;
const client = createClient({
serviceDomain: 'YOUR_DOMAIN',
apiKey: 'YOUR_API_KEY',
});
</script>
After, How to use get
it below.
client
.get({
endpoint: 'endpoint',
queries: { limit: 20, filters: 'createdAt[greater_than]2021' },
})
.then((res) => console.log(res))
.catch((err) => console.error(err));
client
.get({
endpoint: 'endpoint',
contentId: 'contentId',
queries: { fields: 'title,publishedAt' },
})
.then((res) => console.log(res))
.catch((err) => console.error(err));
And, Api corresponding to each content are also available. example.
client
.getList({
endpoint: 'endpoint',
})
.then((res) => console.log(res))
.catch((err) => console.error(err));
client
.getListDetail({
endpoint: 'endpoint',
contentId: 'contentId',
})
.then((res) => console.log(res))
.catch((err) => console.error(err));
client
.getObject({
endpoint: 'endpoint',
})
.then((res) => console.log(res))
.catch((err) => console.error(err));
Get all content ids
This function can be used to retrieve all content IDs only.
Since filters
and draftKey
can also be specified, it is possible to retrieve only the content IDs for a specific category, or to include content from a specific draft.
The alternateField
property can also 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',
})
.then((res) => console.log(res))
.catch((err) => console.error(err));
client
.getAllContentIds({
endpoint: 'endpoint',
filters: 'category[equals]uN28Folyn',
})
.then((res) => console.log(res))
.catch((err) => console.error(err));
client
.getAllContentIds({
endpoint: 'endpoint',
draftKey: 'draftKey',
})
.then((res) => console.log(res))
.catch((err) => console.error(err));
client
.getAllContentIds({
endpoint: 'endpoint',
alternateField: 'url',
})
.then((res) => console.log(res))
.catch((err) => console.error(err));
Get all contents
This function can be used to retrieve all content data.
client
.getAllContents({
endpoint: 'endpoint',
})
.then((res) => console.log(res))
.catch((err) => console.error(err));
client
.getAllContents({
endpoint: 'endpoint',
queries: { filters: 'createdAt[greater_than]2021', orders: '-createdAt' },
})
.then((res) => console.log(res))
.catch((err) => console.error(err));
CREATE API
The following is how to use the write system when making a request to the write system API.
client
.create({
endpoint: 'endpoint',
content: {
title: 'title',
body: 'body',
},
})
.then((res) => console.log(res.id))
.catch((err) => console.error(err));
client
.create({
endpoint: 'endpoint',
contentId: 'contentId',
content: {
title: 'title',
body: 'body',
},
})
.then((res) => console.log(res.id))
.catch((err) => console.error(err));
client
.create({
endpoint: 'endpoint',
content: {
title: 'title',
body: 'body',
},
isDraft: true,
})
.then((res) => console.log(res.id))
.catch((err) => console.error(err));
client
.create({
endpoint: 'endpoint',
contentId: 'contentId',
content: {
title: 'title',
body: 'body',
},
isDraft: true,
})
.then((res) => console.log(res.id))
.catch((err) => console.error(err));
UPDATE API
client
.update({
endpoint: 'endpoint',
contentId: 'contentId',
content: {
title: 'title',
},
})
.then((res) => console.log(res.id))
.catch((err) => console.error(err));
client
.update({
endpoint: 'endpoint',
content: {
title: 'title',
},
})
.then((res) => console.log(res.id))
.catch((err) => console.error(err));
DELETE API
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.
type Content = {
text: string,
}
client.getList<Content>({
client.getListDetail<Content>({
client.getObject<Content>({
The type of getAllContentIds
is as follows.
client.getAllContentIds({
Write functions can also be performed type-safely.
type Content = {
title: string;
body?: string;
};
client.create<Content>({
endpoint: 'endpoint',
content: {
title: 'title',
body: 'body',
},
});
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
Clients can be created for the Management API.
How to use
First, create a client.
import { createManagementClient } from 'microcms-js-sdk';
const client = createManagementClient({
serviceDomain: 'YOUR_DOMAIN',
apiKey: 'YOUR_API_KEY',
});
UploadMedia API
Media files can be uploaded using the 'POST /api/v1/media' endpoint of the Management API.
Node.js
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));
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));
client
.uploadMedia({
data: 'https://example.com/image.png',
})
.then((res) => console.log(res))
.catch((err) => console.error(err));
Browser
const file = document.querySelector('input[type="file"]').files[0];
client
.uploadMedia({
data: file,
})
.then((res) => console.log(res))
.catch((err) => console.error(err));
client
.uploadMedia({
data: 'https://example.com/image.png',
})
.then((res) => console.log(res))
.catch((err) => console.error(err));
Type Definition
UploadMedia
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