As a developer, I always prefer to work with the latest front-end technologies to develop my web applications. But it is also critical for me that the content authors I interact with have a top-notch experience when creating and modifying their pages efficiently and visually.

To support this idea, we have introduced our new JavaScript SDK.

This SDK exists for three key reasons:

1. Allowing developers to easily interact with the dotCMS APIs.

2. Rendering dotCMS pages by providing specific UI components for different frameworks.

3. Enabling the Universal Visual Editor (UVE) in web applications.

This is essential to our vision of a Universal CMS, where hybrid-headless and headless features converge to provide the best possible user experience.

@dotcms/client

dotCMS has many APIs. They’re great to work with, and you can mix and match them to build your pages and routes.

These APIs can be easily consumed by fetch requests in your web app, but we went a step further and created a library that allows you to easily connect to any dotCMS instance to retrieve your data and contentlets (content items).

This library is called @dotcms/client and is published on Node Package Manager (npm). It uses JavaScript ES Module, and it can be used either in the browser or in your favorite JavaScript runtime like Node.js, Bun, and others.

You can start using it in less than a minute. First, install it from npm:

$ npm install @dotcms/client

In your JavaScript project, import the function to create the client:

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

Now, you can initialize the client in your project.

const client = dotcmsClient.init({
    dotcmsUrl: 'https://your.dotcms.com',
    authToken: 'YOUR_DOTCMS_AUTH_TOKEN',
    siteId: 'THE_SITE_ID',
    requestOptions: {
        // In production you might want to deal with this differently
        cache: 'no-cache'
    }
});

Let’s go through these options:

1. dotcmsUrl: The absolute URL of the dotCMS you want to connect to.

2. authToken: The user token can be created inside the dotCMS UI or via REST API. Ensure that the user has the necessary permissions; a ‘read’ token may suffice. If utilizing a ‘write’ token, consider moving this request to the server-side. If the library is being used client-side in the browser, be mindful that the token will be exposed.

3. siteId Since dotCMS is multisite, you can have more than one site inside the dotCMS instance. Here, you should pass the site identifier of the site you want to connect to. If no site is passed, it will fall back to the default site.

4. requestOptions Under the hood, we still use the fetch API to do the request. In case you would like to modify the request to pass different options, this property is exactly for that. It will accept any of the parameters the native fetch function takes. Note: It will ignore body and method because we need to control those in the library (to ensure that the REST endpoints are requested correctly).

This function will return a client object that will expose methods to interact with the dotCMS APIs:

1. client.page will allow you to fetch pages from the Page API

2. client.nav will interact with the Navigation API

3. client.content will let you get any kind of content from dotCMS

And more will be coming soon, like client.workflow, client.users, and client.auth.

@dotcms/react and @dotcms/angular

Now you have the data, but how can you render the page? We’ve got you covered: the components library provides UI components out of the box to render any dotCMS page. You don’t have to worry about doing any CSS math to render rows and columns with consideration for their width and offset.

Of course, we know you want to use your own branding, color, typography, and so on. We built this library with that in mind; you can use any CSS library like Tailwind, Bulma, or even static CSS. Also, if you would like to use your own UI components library you are free to do it; these libraries are completely agnostic.

Now, let me walk you through using the React version. First, in your React, Next.js, Astro, or Remix project, use npm to install:

$ npm install @dotcms/react

Then, in the page or file where you need to render the page, import the component:

import { DotcmsLayout } from "@dotcms/react";

export function MyPage({ page }) {
  return (
    <main className="container flex flex-col gap-8 m-auto">
      <DotLayout entity={{ components, ...page }} />
    </main>
  );
}

Now, in this example, our <MyPage /> component receives the Page API response as a prop, and we can pass it directly to the <DotLayout />. But what is that components object?

Page Components

Users will be adding different kinds of content to their pages. It could be a blog post, a product page, a banner, or any other content type; you just need to tell the <DotLayout /> component how each one of those pieces of content will look on the page. That’s why we need to pass a map of components as a property.

The components object will look like this:

function MyCustomProduct({name, price}) {
  return <>
    <h1>{title}</h1>
    <p>{price}</p>
  </>
}

const components = {
  product: MyCustomProduct,
  blog: ...
}

The object key is the content type variable name and the value is the React component you want to use to render that type of content on the page.

The components within the object, when rendered on the page by the <DotLayout /> component, will receive the contentlets object as a prop. This means that each component will have access to all the properties of that piece of content.

There are way more options for this library; for more information, please refer to our documentation.

Universal Visual Editor

And as for integration with the Universal Visual Editor (UVE)? Surprise! No extra steps are needed. It’s seamlessly integrated to keep editing smooth and simple. By using the libraries in our JavaScript SDK, we ensure that your headless pages are fully editable through the Universal Visual Editor. 

Our SDK empowers you to create rich, dynamic web pages with your preferred technologies, all while leveraging the robust content management capabilities of dotCMS.

In conclusion, the new dotCMS JavaScript SDK bridges the gap between developer preferences and content authoring needs. At dotCMS, we are proud to lead this evolution, enabling you to build cutting-edge web applications without sacrificing any aspect of the content editing experience.