JavaScript Client

The official JavaScript and Typescript client for the Contento Content API

For Next.js and Visual Preview support, see the Next.js toolkit docs.

Installation

npm install @gocontento/client

Basic usage

In most scenarios you will want to create a client once for the whole application, then re-use it whenever you make calls to the Contento API.

To assist in that, we have a createContentoClient() function that you can use:

import { createContentoClient } from "@gocontento/client";

// Create the client
const client =  createContentoClient({
    apiURL: "https://app.contento.io/api/v1",
    apiKey: "your_api_key",
    siteId: "your_site_id",
    isPreview: false,
});

Once you have the client instance, you can start fetching data. For example, you can use the ID of a page with the getContentById() method like so:

// Fetch a content object using the ID
const page = await client.getContentById("some_content_id");

Or, you can fetch a list of content using getContentByType()

// Fetch some content by type
const contentResponse = await client.getContentByType({
    contentType: "content_type_handle"
});

// Get the array of objects from the response
const contentData = contentResponse.content;

// Or, fetch the next page in the list
const nextPageResponse = await contentResponse.nextPage();

Creating a client instance

Use the createContentoClient() function to create a new ContentoClient instance. This method takes one parameter, which is a ContentoClientConfig object with the following properties.

Example

// 1. Import the createContentoClient method 
import { createContentoClient } from "@gocontento/client";

// 2. Initialize the client instance with your settings
const client =  createContentoClient({
    apiURL: "https://app.contento.io/api/v1",
    apiKey: "your_api_key",
    siteId: "your_site_id",
    isPreview: false,
});

It’s a good idea to store those settings in your .env or something similar. Here’s how that might look:

.env

CONTENTO_API_URL=https://app.contento.io/api/v1
CONTENTO_API_KEY=your_api_key
CONTENTO_SITE_ID=your_site_id

lib/contento.js

import { createContentoClient } from "@gocontento/client";

export function createClient() {
    return createContentoClient({
        apiURL: process.env.CONTENTO_API_URL ?? "",
        apiKey: process.env.CONTENTO_API_KEY ?? "",
        siteId: process.env.CONTENTO_SITE_ID ?? "",
        isPreview: false,
    });
}

ContentoClient

The client returned from the createContentoClient() function is an Object with various methods available.

getContentById()

Fetch a content object by its ID: getContentById(id).

Returns a Promise that resolves to a content object.

Example

const page = await client.getContentById("some_content_id");

getContentBySlug()

Fetch a content object by its slug: getContentBySlug(slug, contentType).

Returns a Promise that resolves to a content object.

Example

const content = await client.getContentBySlug("welcome-to-my-new-blog", "blog_post");

getContentByType()

Fetch an array of content objects, filtered within a given content type: getContentByType(options).

This method takes an Object of options with the following properties.

Returns a Promise that resolves to a ContentAPIResponse object.

Examples

Get the first page of content objects, like you might want on a blog index page.

const response = await client.getContentByType({
     contentType: "blog_post"
});

const contentArray = response.content;

Get all pages of content in a given content type.

let response = await client.getContentByType({
    contentType: "blog_post",
    sortBy: "published_at",
    sortDirection: "desc"
})

let content = [...response.content];

// Build an array of content until there are no more pages
while(response.nextPage){
    response = await response.nextPage();
    content = content.concat(response.content);
}

getContent()

A thin wrapper for the Content API: getContent(options).

This method takes an Object of options with the following properties.

Returns a Promise that resolves to a ContentAPIResponse object.

Examples

Get the 3 latest blog posts created by a specific user.

const response = await client.getContent({
    content_type: "blog_post",
    author: "some_author_id",
    limit: 3
});
const posts = response.content;

Get all blog posts in alphabetical order, we limit by 50 here to reduce the overall number of requests.

let response = await client.getContent({
    content_type: "blog_post",
    sort_by: "name",
    sort_direction: "asc",
    limit: 50
});
let content = [...response.content];

// Build an array of content until there are no more pages
while(response.nextPage){
    response = await response.nextPage();
    content = content.concat(response.content);
}

ContentAPIResponse

This response object is returned by many of the ContentoClient methods and has the following properties.