Quick Start

This guide will show you how to get started using Contento if you’re starting from scratch in the CMS and with your own React / Next.js codebase.

Check out the Next.js documentation for system requirements before you get started.

1 - Project setup

Create a new Next.js project in your desired folder:

npx create-next-app@latest

You can choose the appropriate settings for your own project. We typically use Typescript and Tailwind CSS in our projects.

2 - Environment variables

Create a .env file in the root of your codebase.

Then add the following variables to it:

CONTENTO_API_URL=https://app.contento.io/api/v1
CONTENTO_SITE_ID=your-site-id
CONTENTO_API_KEY=your-api-key

3 - Create your Contento account

Create your account with Contento by heading to app.contento.io/register.

4 - Create an API key

Go to your Account Settings in the left hand sidebar.

Then to the API Keys tab.

Click the “Add new” button and give your API Key a relevant name. This would typically be the site name, an environment label like prod or dev, or a combination of both.

Click create and copy the API Key to your clipboard. The API Key will not be shown to you again for security purposes so make sure you keep it safe.

You can then paste your API Key into the CONTENTO_API_KEY variable where it says your-api-key:

CONTENTO_API_URL=https://app.contento.io/api/v1
CONTENTO_SITE_ID=your-site-id
CONTENTO_API_KEY=your-api-key <-------- THIS ONE

5 - Create a new site in Contento

Go to the Sites tab in the left hand sidebar.

Click “Create new site” and you will be given the option to use one of our Starter Kits or to start from scratch.

Choose the Start from Scratch option, give your new site a name and add the full domain name - for now this can usually be http://localhost:3000. You can also choose which team you want this site to be a part of if you have more than one team within your Contento dashboard.

Your site will then be created within your chosen team and you will be taken to the Manage Content Types tab within your freshly created site.

6 - Get your site ID

Go to the menu in the top left of the screen and click Manage Sites and Teams.

Find the site you just created under your team and copy the Site ID to your clipboard.

Paste the Site ID into your .env file into the CONTENTO_SITE_ID variable where it says your_site_id:

CONTENTO_API_URL=https://app.contento.io/api/v1
CONTENTO_SITE_ID=your-site-id <-------- THIS ONE
CONTENTO_API_KEY=your-api-key

7 - Install the SDK

Now we have the basic site and authorisation set up we need a way to call the [Content API][/docs/content-api/v1] so we can get fetch from your site. To help with this we are going to install the Contento JavaScript SDK.

The SDK provides helper functions for making API calls and also object types for those using Typescript that correlate to the fields available in Contento.

Install the SDK with the following command:

npm install @gocontento/client

Within your root folder create a new folder called lib and then create a new file called contento.ts.

In this file we will import the createContentoClient helper function from the SDK and then create a function called createClient() that gets your environment variables from your .env file and adds them to the helper function. We can then reuse this function across the whole app anytime you need to make a call to the API.

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,
    });
}

If you are using Typescript you can also add in your type checks by importing ContentoClient from the SDK and adding it into the function declaration.

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

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

8 - Create a content type

For testing purposes we will now create a general page content type within your site. Go to your site in Contento and then into the Manage Content Types.

Click “add a content type” and select the Page subtype. Give it the name General Page, the handle will automatically populate as general_page. Then add a dynamic slug using {slug} and click Create.

The General Page content type will then automatically populate with a text field called Title that is used as the page name. If you were populating a real content type here you would now add all the other fields you might need, but for the sake of getting things up and running we will stick with just the title field. Click Save and then go to the Content tab.

Now when you click “Add new” your new content type will appear as an option.

Create a new page using the new General Page content type and give it the name “Home”. Now you can publish the page which will make it available in the Content API.

9 - Fetch & render your content

In the page.ts file in the app folder we are going to replace the Home function with our own page function.

This will call the API using the createClient() function we created and request content from the API using the getContentBySlug helper function from the SDK. This will look for content that matches the slug home and the content type general_page and output the page title in the html.

You also need to import the notFound() function from Next.js to handle any errors and don’t forget to import the createClient() function we made from the contento.ts file. If you would like to see what other functions are available for getting content from the API check out the docs here.

import { createClient } from "@/lib/contento";
import { notFound } from "next/navigation";

export default async function page() {
  const content = await createClient()
    .getContentBySlug("home", "general_page")
    .catch(() => {
      notFound();
    });

  console.log(content)

  return (
    <main>
      <div>
        <h1>{content.fields.title.text}</h1>
      </div>
    </main>
  );
}

So you can see the data that is coming from the API, there is a console.log(content) below the content variable. You should see data for the homepage we created that looks something like the data below in your terminal.

We are able to output the title field on the Home page by using dot notation to access the text field in the title object within the fields object of the content variable we created during the API call: content.fields.title.text.

{
  "id": "c_01hvP4mve6p5a7BHe5sR3Q7qWw",
  "published_at": "2024-04-17T13:42:03+00:00",
  "slug": "home",
  "name": "Home",
  "uri": "home",
  "url": "https://www.example-site.com/home",
  "created_at": "2024-04-17T13:41:24+00:00",
  "updated_at": "2024-04-17T13:41:33+00:00",
  "author": {
    "id": "u_01hv8wF8as1HnV6nBDhwe13HDx",
    "name": "Hollie Duncan",
    "email": "[email protected]",
    "profile_photo_url": "https://ui-avatars.com/api/?name=H+D&bold=true&size=256&color=008673&background=00D6B5&font-size=0.4&format=svg"
  },
  "content_type": {
    "id": "ct_01hvp4C5c5PA2BJ6HQWKV54xBj",
    "name": "General Page",
    "handle": "general_page",
    "object_type": "page"
  },
  "fields": {
    "title": {
      "id": "f_01hvp4C5cDPkzFdq1S6hQ50DM9",
      "name": "Title",
      "handle": "title",
      "help_text": null,
      "type": "text",
      "text": "Home"
    }
  }
}

10 - Run the dev server

Run your development server by running the following command or the command specific to your setup:

npm run dev

Typically, this will load your site on http://localhost:3000 — open this in the browser and you should now see the page title “Home” output on the page.

Congratulations you have officially set up your new site in Contento and are fetching and rendering data with Next.js!