The @dotcms/client library is responsible for interacting directly with dotCMS, securely performing Page API and Navigation API — and, soon, Content API — calls from your front-end web app or a Node.js server.
Installation
Installation can be performed via package manager. Choose any of the following commands:
npm install @dotcms/client
pnpm install @dotcms/client
yarn add @dotcms/client
Initialization and Usage
First, you need to import the dotcmsClient, which creates a dotCMS client.
import { dotcmsClient } from '@dotcms/client';
dotcmsClient exposes an init method that that takes a configuration object with the following keys:
| Key | Value |
|---|---|
dotcmsUrl | URL for the dotCMS instance the remote website or application will be calling. For security reasons, we highly recommend passing this value through an environment file variable. |
authToken | dotCMS API token. For security reasons, we highly recommend passing this value through an environment file variable. |
siteId | Optional. The identifier for the dotCMS Site to be accessed. If not specified, falls back to the default site of the instance. |
requestOptions | Optional. An object containing options to pass via the JavaScript Fetch API, used by the library to make its calls to dotCMS. Note that body and method options are not taken into account. |
For example:
import { dotcmsClient } from '@dotcms/client';
const client = dotcmsClient.init({
dotcmsUrl: process.env.NEXT_PUBLIC_DOTCMS_HOST,
authToken: process.env.DOTCMS_AUTH_TOKEN,
siteId: '59bb8831-6706-4589-9ca0-ff74016e02b2',
requestOptions: {
cache: 'no-cache'
}
});
Once initialized, the client contains two properties, page and nav — i.e., one for each API. Each property exposes a single asynchronous get method. Additional methods covering other API endpoints, such as delete or update operations, are planned for future releases.
| Method | Argument | Response |
|---|---|---|
{client}.page.get(options) | PageApiOptions object | A Promise that resolves to a JSON object containing a Page API response. |
{client}.nav.get(options) | NavApiOptions object | A Promise that resolves to a JSON object containing a Navigation API response. |
Each takes a distinctive object as its argument, the full specifications are provided in the following subsections.
client.page.get(opts) Method
| PageApiOptions Property | Value | Description |
|---|---|---|
path | String | The path of the page to access. |
siteId | String | Optional. The identifier of the Site being accessed. If not provided, it will fall back to the one configured for the client object. |
language_id | Number | Optional. The Page's numeric language identifier. Defaults to the Site's default language. |
personaId | String | Optional. The identifier or the key tag of the persona for which the Page should be retrieved. |
fireRules | Boolean | Optional. Whether to fire rules on the Page. Defaults to false. |
depth | Number | Optional. Includes related content via Relationship fields, by up to as many steps as the number specified. Defaults to 0. |
A call to this method might look like this:
const data = await client.page.get({
path: '/blog',
language_id: 1,
personaId: '34b720af-4b46-4a67-9e4b-2117071d01f1'
});
client.nav.get(opts) Method
| NavApiOptions Property | Value | Description |
|---|---|---|
path | String | The root path from which to begin traversing the directory tree. |
depth | Number | Optional. Depth of the folder tree to return. A value of 1 (default) returns only the element specified in the path property; 2 includes any children, if the path specifies a folder; and 3 includes all children and grandchildren. |
language_id | Number | Optional. The Page's numeric language identifier. Defaults to the Site's default language. |
An example of a call:
const nav = await client.nav.get({
path: '/',
depth: 2,
languageId: 1
});
