Get Started with Typescript Utils Library
This guide will help you get started with Contentstack TypeScript Utils SDK to build apps powered by Contentstack.
Prerequisites
To get started with the TypeScript Utils SDK, you will need:
- Node.js Version 22 or later
SDK Installation and Setup
NoteIf you are using the TypeScript Contentstack SDK, you don't need to run the command as @contentstack/utils is already imported in the SDK.
Use the following command to install Contentstack TypeScript Utils SDK:
npm i @contentstack/utils
Usage
Let's learn how you can use Typescript Utils SDK to render embedded items.
Create Render Option
To render embedded items on the front-end, use the renderOption function, and define the UI elements you want to show in the front-end of your website, as shown in the example below:
const renderOption = {
// to render Supercharged RTE NodeType content like paragraph, link, table, order list, un-order list and more.
p: (node, next) => {
`<p class='class-id'>${next(node.children)}</p>` // you will need to call next function with node children contents
}
h1: (node, next) => {
`<h1 class='class-id'>${next(node.children)}</h1>` // you will need to call next function with node children contents
}
// to render Supercharged RTE MarkType content like bold, italic, underline, strikethrough, inlineCode, subscript, and superscript
bold: (text) => {
`<b>${text}</b>`
}
//to render block-type embedded items
block: {
'product': (entry, metadata) => {
'<div>
<h2>{entry.title}</h2>
<img src={entry.product_image.url} alt={entry.product_image.title}/>
<p>{entry.price}</p>
</div>'
},
//to render the default
'$default': (entry, metadata) => {
'<div>
<h2>{entry.title}</h2>
<p>{entry.description}</p>
</div>'
}
},
//to display inline embedded items
inline: {
'$default': (entry) => {
'<span><b>{entry.title}</b> - {entry.description}</span>'
}
},
//to display embedded items inserted via link
link: (entry, metadata) => {
'<a href="{metadata.attributes.href}">{metadata.text}</a>'
},
// to display assets
display: (asset, metadata) => {
return `<img src=${asset.url || metadata.attributes.src || metadata.attributes['asset-link']} alt=${metadata.alt} />`
}
}Basic Queries
Contentstack Utils SDK lets you interact with the Content Delivery APIs and retrieve embedded items from the RTE field of an entry.
Fetch Embedded Item(s) from a Single Entry
Render HTML RTE Embedded object
To get an embedded item of a single entry, you need to provide the stack API key, environment name, delivery token, content type and entry UID. Then, use the includeEmbeddedItems and Contentstack.Utils.render functions as shown below:
import contentstack, { stackconfig } from '@contentstack delivery-sdk' const params: apikey: '<api_key>' , deliverytoken: '<environment_specific_delivery_token>' environment: '<environment>' stack="contentstack.stack(params)" result="await" .contenttype('<content_type_uid>') .entry('<entry_uid>') .includeembeddeditems() .fetch<blogpostentry>(); contentstack.utils.render({ result, renderoption })If you have multiple HTML-based RTE fields in an entry and want to fetch the embedded items from a particular RTE field, you need to provide a path of those RTE fields.
Refer to the example code below:
//code to render embedded item from an RTE field and from another RTE field nested within a group field
contentstack.Utils.render({ entry, path: ["rte_fieldUid", "group.rtefieldUID"], renderOption })Render JSON RTE Contents
To get a single entry, you need to provide the stack API key, environment name, delivery token, content type and entry UID. Then, use the Contentstack.Utils.jsonToHTML function as shown below:
import contentstack, { StackConfig } from '@contentstack/delivery-sdk'
const params: StackConfig = {
apiKey: '<API_KEY>',
deliveryToken: '<ENVIRONMENT_SPECIFIC_DELIVERY_TOKEN>',
environment: '<ENVIRONMENT>',
}
const stack = contentstack.stack(params)
const result = await stack
.contentType('<CONTENT_TYPE_UID>')
.entry('<ENTRY_UID>')
.includeEmbeddedItems()
.fetch<BlogPostEntry>();
Contentstack.Utils.jsonToHTML({
entry: result,
paths: ["rte_fieldUid", "group.rteFieldUID"],
renderOption
})Note To get all embedded items while fetching an entry with a JSON RTE field use includeEmbeddedItems function.
Fetch Embedded Item(s) from Multiple Entries
Render HTML RTE Embedded object
To get embedded items from multiple entries, you need to provide the content type UID. You can also use the path variable in case the entries have multiple HTML-based RTE fields.
import contentstack, { StackConfig } from '@contentstack/delivery-sdk'
const params: StackConfig = {
apiKey: '<API_KEY>',
deliveryToken: '<ENVIRONMENT_SPECIFIC_DELIVERY_TOKEN>',
environment: '<ENVIRONMENT>',
}
const Stack = contentstack.stack(params)
const result = await stack
.contentType('<CONTENT_TYPE_UID>')
.entry()
.includeEmbeddedItems()
.find<BlogPostEntry>();
result.entries.forEach(entry => {
contentstack.Utils.render({
entry,
paths: ["rte_fieldUid", "group.rteFieldUID"],
renderOption
})
})Render JSON RTE contents
To get multiple entries, you need to provide the stack API key, environment name, delivery token, content type and entry UID. Then, use the Contentstack.Utils.jsonToHTML function as shown below:
import contentstack, { StackConfig } from '@contentstack/delivery-sdk'
const params: StackConfig = {
apiKey: '<API_KEY>',
deliveryToken: '<ENVIRONMENT_SPECIFIC_DELIVERY_TOKEN>',
environment: '<ENVIRONMENT>',
}
const Stack = contentstack.stack(params)
const result = await stack
.contentType('<CONTENT_TYPE_UID>')
.entry()
.includeEmbeddedItems()
.find<BlogPostEntry>();
result.entries.forEach(entry => {
contentstack.Utils.jsonToHTML({
entry,
paths: ["rte_fieldUid", "group.rteFieldUID"],
renderOption
})
})- To get all embedded items while fetching an entry with a JSON RTE field use includeEmbeddedItems function.
- The methods jsonToHTML() and htmlToJson() allow you to transform data between JSON and HTML formats.
Resolve Embedded Item Metadata
The SDK resolves embedded entry and asset metadata from the _embedded_items object in the API response and exposes the resolved values at node.attrs._resolved. Read resolved values from there so that your rendered output reflects the current state of the embedded item. The legacy node.attrs['asset-link'] property, and the equivalent properties for other node types, remain readable as a soft-deprecated fallback.
Note The includeEmbeddedItems() method retrieves first-level embedded items only. To retrieve embedded items that are nested inside other embedded items, request the entry directly through the Content Delivery API with include_embedded_items[]=RECURSIVE.
Additional Resources
- Refer to Embed Entries or Assets to understand how embedded item data is stored and resolved.
- Refer to CDA | Entries for the include_embedded_items[] and embedded_items_depth parameter reference.