JavaScript SDK: Client Library

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 Basic Usage

First, you need to import the dotcmsClient, which creates a dotCMS client. You can use the ES (or JS) module syntax as follows:

import { dotcmsClient } from '@dotcms/client';

CommonJS syntax is also supported:

const { DotCmsClient } = require('@dotcms/client');

dotcmsClient exposes an init method that that takes a configuration object with the following keys:

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.

Each takes a distinctive object as its argument, the full specifications are provided in the following subsections.

client.page.get(opts) Method

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

An example of a call:

const nav = await client.nav.get({
    path: '/',
    depth: 2,
    languageId: 1
});

Content Queries

The client library offers straightforward ways to perform queries for content within the dotCMS system through JavaScript methods.

Building Queries With the Query Builder Syntax

The client library includes a QueryBuilder class that allows the construction of content queries in a style more natural to a JavaScript environment, without needing to manually build the Lucene query syntax strings used by the system.

For instance:

const queryForBlogsOrArticles = queryBuilder
            .field('contentType')
            .equals('Blog')
            .or()
            .equals('Article')
            .build();

The table below outlines its methods:

The following example displays all of the builder class's methods, generating a complex Lucene query:

let queryBuilder = new QueryBuilder();
const myQuery = queryBuilder
            .field('contentType')
            .equals('Blog')
            .or()
            .equals('Activity')
            .excludeField('conhost')
            .equals('my-super-cool-site')
            .field('languageId')
            .equals('2') // spanish
            .and()
            .field('deleted')
            .equals('false')
            .raw('+summary:Snowboard')
            .not()
            .equals('Swiss Alps')
            .build();

The above myQuery variable will have the following value:

+contentType:Blog OR Activity -conhost:my-super-cool-site +languageId:2 AND +deleted:false +summary:Snowboard NOT “Swiss Alps”

For additional examples, see the class's specification page on GitHub.

Performing the Query

The getCollection method allows you to fetch a collection of content items using the queries built in the manner indicated above. Once you have initialized your client object, the fetch can be performed through the following method:

client.content.getCollection()

The getCollection() method, in its most basic form, accepts as an argument a string specifying the system name of a content type — e.g.: client.content.getCollection('Blog'). However, there are also further methods specifying parameters of this fetch operation. A more complex query might be executed as follows:

client.content
    .getCollection('Destination')
    .sortBy([
        {
            field: 'modDate',
            order: 'desc'
        }
    ])
    .limit(3)
    .depth(0)
    .sortBy([{ field: 'title', order: 'asc' }, { field: 'modDate', order: 'desc' }])
    .query((queryBuilder) => 
        queryBuilder.field('title').equals('Hello World').or().equals('Hello World 2')
    )
    .fetch()
    .then((response) => {
        setDestinations(response.contentlets);
    })
    .catch((error) => {
        console.error(`Error fetching Destinations`, error);
    });

Below is a full list of methods that supplement a getCollection() call.

This method can be used with either await or then-style asynchronous calls.