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:
Allowing developers to easily interact with the dotCMS APIs.
Rendering dotCMS pages by providing specific UI components for different frameworks.
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 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:
dotcmsUrl: The absolute URL of the dotCMS you want to connect to.
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.
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.
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:
client.page will allow you to fetch pages from the Page API
client.nav will interact with the Navigation API
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.
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 (
);
}
Now, in this example, our
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
The components object will look like this:
function MyCustomProduct({name, price}) {
return <>
{title}
{price}
>
}
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
There are way more options for this library; for more information, please refer to our documentation.
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.
Explore the transformative journey of dotCMS as it unveils a new design system that harmonizes user interfaces and enhances cross-team collaboration.
Explore how design tokens streamline consistency and adaptability across digital platforms, essential for modern design systems.
dotCMS has enhanced our customers' experience by embracing continuous delivery (CD) practices.