JavaScript SDK: Client Library

Last Updated: Sep 25, 2024
documentation for the dotCMS Content Management System

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:

KeyValue
dotcmsUrlURL 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.
authTokendotCMS API token. For security reasons, we highly recommend passing this value through an environment file variable.
siteIdOptional. The identifier for the dotCMS Site to be accessed. If not specified, falls back to the default site of the instance.
requestOptionsOptional. 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.

MethodArgumentResponse
{client}.page.get(options)PageApiOptions objectA Promise that resolves to a JSON object containing a Page API response.
{client}.nav.get(options)NavApiOptions objectA 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 PropertyValueDescription
pathStringThe path of the page to access.
siteIdStringOptional. The identifier of the Site being accessed. If not provided, it will fall back to the one configured for the client object.
language_idNumberOptional. The Page's numeric language identifier. Defaults to the Site's default language.
personaIdStringOptional. The identifier or the key tag of the persona for which the Page should be retrieved.
fireRulesBooleanOptional. Whether to fire rules on the Page. Defaults to false.
depthNumberOptional. 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 PropertyValueDescription
pathStringThe root path from which to begin traversing the directory tree.
depthNumberOptional. 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_idNumberOptional. 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
});

On this page

×

We Dig Feedback

Selected excerpt:

×