Ever heard of the concept of keeping your code DRY?
Don’t Repeat Yourself — one of the key fundamentals of Clean Code — is key to reducing workload, saving time, and cutting costs in your applications. You don’t want to reinvent the wheel, get stuck in copy-paste hell, or worse — rewrite the same code in every project where you need it.
That’s why we have APIs, libraries, and the star of this post: SDKs.
But then come the big questions: What’s an SDK? How does it help? Why should you bother making one? And most importantly — how do you do it?
What’s an SDK?
An SDK (Software Development Kit) is a set of tools, APIs, libraries, and documentation that helps you interact with a platform — dotCMS in this case — without worrying about low-level API calls or complex logic.
How Does It Help?
As a developer, you don’t want to spend time handling all the under-the-hood complexity of making a platform work with your app or website. You just want to build your product — fast and well.
That’s exactly why SDKs exist. Instead of wasting time figuring out how to communicate with a platform, you can jump straight into development.
Plus, using an SDK helps you stick to the sacred DRY rule. No reinventing the wheel, no messy copy-paste hacks, and definitely no writing the same code over and over again.
Why Bother Creating One?
Time.
You don’t want to waste time copying, pasting, and rewriting code every time you need something similar.
Not only is that boring, but it also becomes a nightmare to maintain. If you find a bug in one environment where you’ve used that code, you’ll have to track down every implementation, apply the fix manually, and then test each change to make sure it actually works.
Time is a resource, and we need to be smart about how we use it.
Think of an SDK as a long-term investment. Instead of scattering the same logic across multiple projects, an SDK serves as a single source of truth — making your code easier to use, maintain, and extend.
How Do You Create One?
Finally, we’ve reached the big question — how do you actually build an SDK?
Now, I’ll guide you step by step on how to create your own SDK from scratch to interact with the dotCMS Page API and fetch content, so you can build your brand-new webpage in any environment — without wasting time copying and pasting logic.
While this tutorial focuses on TypeScript, the principles you'll learn here — structuring code, handling API requests, and making the SDK reusable — can be applied to building SDKs in any language.
Prerequisites
For this tutorial, I’ll be using the latest LTS version of Node — v22.14 at the time of writing — along with the latest stable version of TypeScript (v5.7.3). Since Node comes with NPM (Node Package Manager), make sure you have it installed as well.
As for the IDE and Terminal, feel free to use whichever you prefer; I’ll be using Cursor and Warp.
Why TypeScript Over JavaScript?
For a project like this — where reliability, maintainability, and scalability matter — TypeScript is the better choice. It helps catch accidental bugs and inconsistencies that plain JavaScript might let slip through, making your SDK more robust from the start.
With all that covered, let’s jump right in
Initialize the project
Choose a folder in your environment and open a terminal. First, create a new folder by running this command:
mkdir dotcms-clientIf the folder was created successfully, navigate to it by running:
cd dotcms-clientNow that we have a folder to store all our code, let’s initialize npm. Run the following command in your terminal:
npm init -yThis will generate a package.json file containing the basic configuration you need.
Next, install TypeScript by running this command:
npm install --save-dev typescriptOnce the installation is complete, it’s time to move over to your IDE and finish the configuration.
You can open the IDE for this folder. If you have Cursor or VSCode properly configured, simply run the command code . in your terminal to open the IDE right away. Alternatively, you can open your IDE manually and navigate to the folder we just created.
Configuring the project
Now, in the root directory of this folder, create the main configuration file for TypeScript: tsconfig.json. Add the following configuration:
{
"compilerOptions": {
"esModuleInterop": true,
"skipLibCheck": true,
"target": "es2022",
"allowJs": true,
"resolveJsonModule": true,
"moduleDetection": "force",
"isolatedModules": true,
"strict": true,
"noUncheckedIndexedAccess": true,
"noImplicitOverride": true,
"module": "NodeNext",
"outDir": "dist",
"sourceMap": true,
"declaration": true,
"lib": ["es2022", "dom", "dom.iterable"]
},
"include": ["src/**/*"]
}Essential tsconfig.json Properties for an SDK
Property | Description |
|---|---|
"outDir": "dist" | Specifies where the compiled .js and .d.ts files will be placed. Without this, compiled files will be stored in the source directory. |
"declaration": true | Generates .d.ts files, ensuring TypeScript users get proper type definitions. Without this, consumers won't have type support. |
"module": "NodeNext” | Determines how modules are compiled: "NodeNext" supports both CommonJS and ESM in Node.js. "ESNext" is best for pure ESM libraries. |
"target": "es2022" (or any modern ES version) | Specifies the ECMAScript version to compile to, ensuring compatibility with the lowest runtime environment you want to support. |
"lib": ["es2022", "dom", "dom.iterable"] | Defines available APIs: "dom" ensures compatibility with browser environments, even though we won’t be using browser APIs in this tutorial. Keeping it helps maintain flexibility for future browser support. |
"esModuleInterop": true | Ensures compatibility between CommonJS and ESM imports, preventing issues with mixed import/export styles. |
"skipLibCheck": true | Speeds up compilation by skipping type checking for third-party libraries. |
"strict": true | Enables all strict TypeScript type-checking rules, improving code quality. |
"include": ["src/**/*"] | Defines which files should be compiled, ensuring the entire src/ directory is included. |
Next, let’s add a command to our package.json. Open the file and look for the scripts property. It should look similar to this:
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
},Now, add the start command with the following value: tsc && node dist/index.js
This will compile the TypeScript code and execute the generated JavaScript, allowing us to run our SDK easily.
Your updated scripts section should now look like this:
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"start": "tsc && node dist/index.js"
}Finally, update the main property to dist/index.js. This tells the module resolution system where to start when importing or building the SDK.
Your final package.json should now look like this:
{
"name": "dotcms-client",
"version": "1.0.0",
"description": "",
"main": "dist/index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"start": "tsc && node dist/index.js"
},
"keywords": [],
"author": "",
"license": "ISC",
"devDependencies": {
"typescript": "^5.7.3"
}
}Adding the required folders
At this point, we’re all set to run our TypeScript project. Now, let’s start building our SDK by setting up the following folder structure:
├── node_modules
├── src/
│ ├── lib/
│ │ ├── client.ts
│ │ └── types.ts
│ └── index.ts
├── package-lock.json
├── package.json
└── tsconfig.jsonThe key addition here is the src/ folder, which will house our SDK logic. Inside it, we have a lib/ folder where the core SDK files will live, and an index.ts file that will serve as the main entry point, exposing the SDK functionality.
Please create these folders and files in order to continue, you can leave the files empty; we will be filling them in the next steps.
Building the client
Now that we’re ready to build the client, let’s quickly go over the API we’ll be working with.
The dotCMS Page API is a set of endpoints that let us fetch a page’s content, structure, and metadata.
This allows us to render pages in a headless environment, giving us full control over how and where we serve the content. It also provides key details needed to integrate the page with the UVE.
In this tutorial, we’ll be using the /api/v1/page/json endpoint. This endpoint of the Page API provides essential information, including the page content, layout, and metadata such as the title, description, current persona, language, and more.
The Page API comes with a long list of parameters that let you fetch a page in a specific state — whether it’s based on a Persona, Date, Language, Experiment Variant, Relationship Depth, or even the Rendered version served by dotCMS.
But to keep things simple, we’ll focus on three key parameters:
path – The exact path where the page is located.
languageID – The language the page was built in.
siteID – The site the page belongs to.
Since we’re building pages per site, the siteID can be treated as a global configuration, which we’ll cover later in the tutorial.
Let’s jump right into the code. Open the types.ts file we created earlier and define the PageAPIParams type with path and languageID as its only properties:
export type PageAPIParams = {
path: string;
languageID?: string;
};Notice that languageID is optional (?). That’s because every page is initially built in a default language before being translated. This means we can safely omit it from the parameters and handle it accordingly in our implementation.
Now, open client.ts, where we’ll define the base of our DotCMSClient class. This class will have a method called getPage, responsible for fetching a page. Here’s the initial setup:
import { PageAPIParams } from './types';
export class DotCMSClient {
constructor() {}
async getPage({ path, languageID }: PageAPIParams) {}
}Defining Configuration Properties
Before we start making requests to dotCMS, we need three key configuration properties:
baseURL – The URL where the dotCMS instance is hosted.
siteId – The site the page belongs to.
token – Security access token required to access the API.
Let’s define a type for this configuration. Go back to types.ts and add the following:
export type PageAPIParams = {
path: string;
languageID?: string;
};
// Your recently created type
export type DotCMSConfig = {
baseURL: string;
siteID: string;
token: string;
};Updating the Client Constructor
Now, let’s use this config in DotCMSClient. Modify client.ts as follows:
import { DotCMSConfig, PageAPIParams } from './types';
export class DotCMSClient {
#token: string;
#siteID: string;
#baseURL: string;
constructor({ baseURL, siteID, token }: DotCMSConfig) {
this.#baseURL = baseURL;
this.#siteID = siteID;
this.#token = token;
}
async getPage({ path, languageID }: PageAPIParams) {}
}We created three private properties (#token, #siteID, #baseURL) that will store the configuration values.
Defining the Page API Path
Next, let’s define a constant for the API endpoint at the top of client.ts:
import { DotCMSConfig, PageAPIParams } from './types';
const PAGE_API_PATH = '/api/v1/page/json';We will be using the JSON variation of the Page API.
Building the API URL
Inside the getPage method, let’s construct the URL safely using the URLSearchParams and URL APIs:
const queryParams = new URLSearchParams();
queryParams.set('host_id', this.#siteID);
queryParams.set('languageId', languageID ?? '1');
const url = new URL(`${PAGE_API_PATH}${path}?${queryParams.toString()}`, this.#baseURL);This ensures the query parameters are properly formatted, and the final URL is constructed in a safe and reliable way.
Handling the Fetch Request
Now, let’s complete the getPage method by adding the fetch logic. The final implementation should look like this:
async getPage({ path, languageID }: PageAPIParams) {
const queryParams = new URLSearchParams();
queryParams.set('host_id', this.#siteID);
queryParams.set('languageId', languageID ?? '1');
const url = new URL(`${PAGE_API_PATH}${path}?${queryParams.toString()}`, this.#baseURL);
const response = await fetch(url, {
headers: {
Authorization: `Bearer ${this.#token}`
}
});
if (!response.ok) {
throw new Error(`Failed to fetch page: ${response.statusText}`);
}
const data = await response.json();
return data;
}This method builds the request URL, makes an authenticated request, and ensures error handling if the request fails.
Final client.ts File
Here’s how your full client.ts should look now:
import { DotCMSConfig, PageAPIParams } from './types';
const PAGE_API_PATH = '/api/v1/page/json';
export class DotCMSClient {
#token: string;
#siteID: string;
#baseURL: string;
constructor({ baseURL, siteID, token }: DotCMSConfig) {
this.#baseURL = baseURL;
this.#siteID = siteID;
this.#token = token;
}
async getPage({ path, languageID }: PageAPIParams) {
const queryParams = new URLSearchParams();
queryParams.set('host_id', this.#siteID);
queryParams.set('languageId', languageID ?? '1');
const url = new URL(`${PAGE_API_PATH}${path}?${queryParams.toString()}`, this.#baseURL);
const response = await fetch(url, {
headers: {
Authorization: `Bearer ${this.#token}`
}
});
if (!response.ok) {
throw new Error(`Failed to fetch page: ${response.statusText}`);
}
const data = await response.json();
return data;
}
}Using the DotCMSClient
Now that our client is ready, let’s test it in our index.ts file. Open the file and add the following code:
import { DotCMSClient } from './lib/client';
const client = new DotCMSClient({
baseURL: '<your-base-url>',
token: '<your-token>',
siteID: '<your-site-id>'
});
(async () => {
const page = await client.getPage({
path: '/',
languageID: '1'
});
console.log(page);
})();Replacing the Placeholders
We need to replace the placeholders (baseURL, siteID, and token) with actual values. For this test, we’ll use the dotCMS demo site.
1. Get an API Token
Log in with:
Email: admin@dotcms.com
Password: admin
Navigate to Users Portlet (Settings > Users)
Click on Admin User
Go to API Access Tokens Tab
Request a New Token
Add a label (it can be anything), then click OK
Copy the generated token and use it as the token in index.ts
2. Get the Site ID
Go to Sites Portlet (Settings > Sites)
Right-click on demo.dotcms.com (Default)
Click Edit
Go to the History tab
Copy the identifier value and use it as siteID in index.ts
3. Set the Base URL
For this test, our base URL will be: https://demo.dotcms.com
Final index.ts Example
Once you've replaced the placeholders, your file should look approximately like this:
import { DotCMSClient } from './lib/client';
const client = new DotCMSClient({
baseURL: 'https://demo.dotcms.com',
token: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhcGliYmI5Y2FjNy1lNzJiLTQzZjUtOTM4ZC01NzljNTRiN2UwN2EiLCJ4bW9kIjoxNzQxMDAzNDUxMDAwLCJuYmYiOjE3NDEwMDM0NTEsImlzcyI6ImE1N2U4Njk5ZDMiLCJleHAiOjE3NDE4Njc0NTEsImlhdCI6MTc0MTAwMzQ1MSwianRpIjoiOWM1N2JkZjItMDFiNC00Yjc3LWFhM2QtZGMxNjRhYTkyMjA0In0.8MFQx2mAqa5uBDKBoOpZr6LPMNQOqQWk1WIt7ORKdu8',
siteID: '48190c8c-42c4-46af-8d1a-0cd5db894797'
});
(async () => {
const page = await client.getPage({
path: '/',
languageID: '1'
});
console.log(page);
})();Important Notes
The dotCMS demo site resets nightly, meaning the token and site ID may become invalid after 24 hours. If the request fails, repeat the steps above to get new credentials.
Security best practice: Never hardcode API tokens in source code. In real-world applications, use environment variables to store sensitive data. Node.js natively supports environment variables since v20.6.0, making it easier to manage secrets securely. However, for simplicity, we’re skipping this step in this tutorial.
Now, navigate to your project’s root folder and run the following command in your terminal:
npm run startIf everything was set up correctly, you should see a large object printed in your terminal, similar to this:
{
entity: {
canCreateTemplate: true,
containers: {
'//demo.dotcms.com/application/containers/default/': [Object],
'//demo.dotcms.com/application/containers/banner/': [Object]
},
layout: {
width: null,
title: 'anonymouslayout1600437132653',
header: true,
footer: true,
body: [Object],
sidebar: [Object],
version: 1
},
numberContents: 20,
page: {
icon: 'pageIcon',
archived: false,
baseType: 'HTMLPAGE',
cachettl: '0',
canEdit: true,
canLock: true,
canRead: true,
canSeeRules: true,
canonicalUrl: '/',
contentType: 'htmlpageasset',
creationDate: 1599065449560,
deleted: false,
extension: 'page',
folder: 'SYSTEM_FOLDER',
friendlyName: 'TravelLux - Your Destination for Exclusive Experiences',
hasLiveVersion: true,
hasTitleImage: true,
host: '48190c8c-42c4-46af-8d1a-0cd5db894797',
hostName: 'demo.dotcms.com',
httpsRequired: false,
identifier: 'a9f30020-54ef-494e-92ed-645e757171c2',
inode: 'bcbe361d-d7a5-4600-8ff7-c24e7c0a1ba9',
isContentlet: true,
languageId: 1,
live: true,
liveInode: 'bcbe361d-d7a5-4600-8ff7-c24e7c0a1ba9',
locked: false,
metaDescription: 'dotCMS provides a user-friendly interface for creating, editing, and publishing content. This starter site is designed to demonstrate some the basic features of dotCMS.',
metaKeywords: 'skiing,vaction,french polynesia,french alps,surfing',
mimeType: 'application/dotpage',
modDate: 1718900846537,
modUser: 'dotcms.org.1',
modUserName: 'Admin User',
name: 'index',
ogDescription: 'dotCMS provides a user-friendly interface for creating, editing, and publishing content. This starter site is designed to demonstrate some the basic features of dotCMS.',
ogImage: '05c35ba2f0f1dcf0404d094f05f764ff',
ogTitle: 'dotCMS Universal Content Management System Demo Site',
ogType: 'website',
owner: 'dotcms.org.1',
ownerName: 'Admin User',
pageTitle: 'dotCMS Demo Site',
pageURI: '/index',
pageUrl: 'index',
path: '/index',
publishDate: 1718900846940,
publishUser: 'dotcms.org.1',
publishUserName: 'Admin User',
searchEngineIndex: 'index,follow,snippet',
shortyId: 'a9f3002054',
shortyLive: 'bcbe361dd7',
shortyWorking: 'bcbe361dd7',
sitemapImportance: '1.0',
sortOrder: 0,
stInode: 'c541abb1-69b3-4bc5-8430-5e09e5239cc8',
statusIcons: "<span class='greyDotIcon' style='opacity:.4'></span><span class='liveIcon'></span>",
template: 'fdc739f6-fe53-4271-9c8c-a3e05d12fcac',
title: 'Home',
titleImage: 'ogImage',
type: 'htmlpage',
url: '/index',
working: true,
workingInode: 'bcbe361d-d7a5-4600-8ff7-c24e7c0a1ba9'
},
site: {
lowIndexPriority: false,
variantId: 'DEFAULT',
systemHost: false,
parent: true,
hostThumbnail: null,
structureInode: '855a2d72-f2f3-4169-8b04-ac5157c4380c',
inode: 'a1de7e5c-d4b4-43ab-866c-98845673fb74',
hostname: 'demo.dotcms.com',
tagStorage: 'SYSTEM_HOST',
aliases: 'localhost\n127.0.0.1',
default: true,
name: 'demo.dotcms.com',
permissionId: '48190c8c-42c4-46af-8d1a-0cd5db894797',
permissionType: 'com.dotmarketing.portlets.contentlet.model.Contentlet',
owner: 'dotcms.org.1',
modDate: 1726154781278,
identifier: '48190c8c-42c4-46af-8d1a-0cd5db894797',
type: 'contentlet',
working: true,
keyValue: false,
categoryId: 'a1de7e5c-d4b4-43ab-866c-98845673fb74',
versionId: '48190c8c-42c4-46af-8d1a-0cd5db894797',
modUser: 'dotcms.org.1',
titleImage: null,
folder: 'SYSTEM_FOLDER',
dotAsset: false,
persona: false,
htmlpage: false,
vanityUrl: false,
indexPolicyDependencies: 'DEFER',
host: 'SYSTEM_HOST',
form: false,
contentTypeId: '855a2d72-f2f3-4169-8b04-ac5157c4380c',
languageVariable: false,
archived: false,
sortOrder: 0,
languageId: 1,
fileAsset: false,
new: false,
live: true,
locked: true,
title: 'demo.dotcms.com'
},
template: {
iDate: 1562013807321,
type: 'template',
owner: '',
inode: 'f2abcf2e-ab71-48c6-9109-a77399ba5204',
identifier: 'fdc739f6-fe53-4271-9c8c-a3e05d12fcac',
source: 'DB',
title: 'anonymous_layout_1600437132653',
friendlyName: '',
modDate: 1600437132877,
modUser: 'dotcms.org.1',
sortOrder: 0,
showOnMenu: false,
body: 'null',
image: '',
drawed: true,
drawedBody: '{"header":true,"footer":true,"body":{"rows":[{"columns":[{"containers":[{"identifier":"//demo.dotcms.com/application/containers/banner/","uuid":"1"}],"widthPercent":100,"leftOffset":1,"styleClass":"banner-tall","preview":false,"width":12,"left":0}],"styleClass":"p-0 banner-tall"},{"columns":[{"containers":[{"identifier":"//demo.dotcms.com/application/containers/default/","uuid":"1"}],"widthPercent":100,"leftOffset":1,"styleClass":"mt-70 booking-form","preview":false,"width":12,"left":0}]},{"columns":[{"containers":[{"identifier":"//demo.dotcms.com/application/containers/default/","uuid":"2"}],"widthPercent":25,"leftOffset":1,"styleClass":"","preview":false,"width":3,"left":0},{"containers":[{"identifier":"//demo.dotcms.com/application/containers/default/","uuid":"3"}],"widthPercent":25,"leftOffset":4,"styleClass":"","preview":false,"width":3,"left":3},{"containers":[{"identifier":"//demo.dotcms.com/application/containers/default/","uuid":"4"}],"widthPercent":25,"leftOffset":7,"styleClass":"","preview":false,"width":3,"left":6},{"containers":[{"identifier":"//demo.dotcms.com/application/containers/default/","uuid":"5"}],"widthPercent":25,"leftOffset":10,"styleClass":"","preview":false,"width":3,"left":9}]},{"columns":[{"containers":[{"identifier":"//demo.dotcms.com/application/containers/default/","uuid":"6"}],"widthPercent":50,"leftOffset":1,"styleClass":"","preview":false,"width":6,"left":0},{"containers":[{"identifier":"//demo.dotcms.com/application/containers/default/","uuid":"7"}],"widthPercent":25,"leftOffset":7,"styleClass":"","preview":false,"width":3,"left":6},{"containers":[{"identifier":"//demo.dotcms.com/application/containers/default/","uuid":"8"}],"widthPercent":25,"leftOffset":10,"styleClass":"","preview":false,"width":3,"left":9}]},{"columns":[{"containers":[{"identifier":"//demo.dotcms.com/application/containers/default/","uuid":"9"}],"widthPercent":100,"leftOffset":1,"styleClass":"","preview":false,"width":12,"left":0}],"styleClass":"bg-white py-5"},{"columns":[{"containers":[{"identifier":"//demo.dotcms.com/application/containers/default/","uuid":"10"}],"widthPercent":100,"leftOffset":1,"styleClass":"","preview":false,"width":12,"left":0}]}]},"sidebar":{"containers":[],"location":"","width":"small","widthPercent":20,"preview":false}}',
countAddContainer: 0,
countContainers: 0,
theme: 'd7b0ebc2-37ca-4a5a-b769-e8a3ff187661',
header: 'null',
footer: 'null',
template: false,
anonymous: true,
versionType: 'template',
deleted: false,
working: true
versionId: 'fdc739f6-fe53-4271-9c8c-a3e05d12fcac',
permissionId: 'fdc739f6-fe53-4271-9c8c-a3e05d12fcac',
archived: false,
live: true,
locked: false,
name: 'anonymous_layout_1600437132653',
permissionType: 'com.dotmarketing.portlets.templates.model.Template',
categoryId: 'f2abcf2e-ab71-48c6-9109-a77399ba5204',
idate: 1562013807321,
new: false,
canEdit: true
},
viewAs: {
visitor: [Object],
language: [Object],
mode: 'PREVIEW_MODE',
variantId: 'DEFAULT'
}
},
errors: [],
i18nMessagesMap: {},
messages: [],
pagination: null,
permissions: []
}This confirms that our SDK is working! 🎉
What’s Next?
Our SDK is up and running, but to make it truly reusable across any JavaScript project, we need to package it properly. In my next blog post, I'll show you how to Build a Universal JavaScript SDK with Rollup.js and publish it to NPM.
You can check out the complete code in this repository.
Stay tuned for more! 🚀