Guides
Starter Kits
This guide will show you how to get started with Contento using our Starter Kits.
We’ll be using the Minimal kit for this guide, but they all follow the same principles.
Each kit comes in two parts, the CMS starter kit which contains the content models, and the codebase written in Next.js & Typescript which you will find on our GitHub.
Pick the codebase which matches the kit you want to work with here:
The Minimal Starter Kit helps you get up and running quickly with a basic page content model, main navigation and footer navigation content models, dynamic routing and a basic <BlockMatcher /> component for creating your own page builder within the CMS.
There is very little styling so that you do not have to spend a lot of time removing our CSS before adding in your own. If you would like a kit with no styling then check out our Basic Starter Kit
The Marketing Website is more advanced, so follow the basic setup instructions in this guide, then head over here for more details on how that particular kit works.
Create your Contento account
Create your account with Contento by heading to app.contento.io/register.
Deploy the kit within Contento
Once you have created your account you will be given the option to pick a Starter Kit from the menu. Select the Minimal one and click next.
You can then select which team you would like your site to be created in. This will default to your personal team if you have just signed up. Click create and our system will work in the background to create this template in your account.
You can read more about each kit from this screen, and view the repo from here as well. It can take up to a couple of minutes for the site to be created so whilst that’s happening let’s get the codebase sorted.
Install the codebase
Go to the GitHub repo for the Minimal Starter Kit. and clone the repo to your local environment.
Open the Starter Kit we just cloned in your code editor, you should have a folder structure that looks like this:
Install all the dependencies by running the following command in your terminal. The template is configured to install the Contento SDK, Next.js, Tailwind CSS, Headless UI and a bunch of other things.
npm install
Environment variables
We will now set up your .env file and get the required ID’s and secrets to access the data from the CMS.
First we’ll rename the .env.sample file to .env.
CONTENTO_SITE_ID
Go back to Contento in your browser, the Minimal Site Starter Kit should now have been created within your chosen team.
Click on the ID and copy it to your clipboard.
Now paste it into your .env file in the CONTENTO_SITE_ID variable where it says your_contento_site_key:
CONTENTO_API_URL=https://app.contento.io/api/v1
CONTENTO_API_KEY=your_contento_api_key
CONTENTO_SITE_ID=your_contento_site_key <------ THIS ONE
CONTENTO_PREVIEW_SECRET=your_contento_preview_secret
SITE_MAIN_NAV_ID=your_main_nav_id
SITE_FOOTER_NAV_ID=your_footer_nav_id
CONTENTO_API_KEY
Next we will create an API Key for this site. Go to the Api Keys section of the Account tab in the left hand sidebar. Click the “Add new” button at the top right of the screen.
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.
Paste your API key into your .env file in the CONTENTO_API_KEY variable where it says your_contento_api_key:
CONTENTO_API_URL=https://app.contento.io/api/v1
CONTENTO_API_KEY=your_contento_api_key <------ THIS ONE
CONTENTO_SITE_ID=your_contento_site_key
CONTENTO_PREVIEW_SECRET=your_contento_preview_secret
SITE_MAIN_NAV_ID=your_main_nav_id
SITE_FOOTER_NAV_ID=your_footer_nav_id
About the code
In the contento.ts file you will see that the Starter Kit uses the createClient helper function from the Contento JavaScript SDK to make a call to the API.
This function takes the CONTENTO_API_URL, CONTENTO_API_KEY and CONTENTO_SITE_ID that we just updated in your .env file and uses these to authenticate your API calls.
Visual preview
Now let’s turn on Visual Preview and get the preview secret. Click into your site in Contento.
Now go to Settings in the top menu, and into the Preview tab in the left hand sidebar. The Enable Visual Preview toggle should already be on, but if it isn’t just toggle it on so the switch is green.
You will then be able to copy your preview secret to your clipboard.
Now paste it into your .env into the CONTENTO_PREVIEW_SECRET variable where it says your_contento_preview_secret:
CONTENTO_API_URL=https://app.contento.io/api/v1
CONTENTO_API_KEY=your_contento_api_key
CONTENTO_SITE_ID=your_contento_site_key
CONTENTO_PREVIEW_SECRET=your_contento_preview_secret <------ THIS ONE
SITE_MAIN_NAV_ID=your_main_nav_id
SITE_FOOTER_NAV_ID=your_footer_nav_id
About the code
In the api > draft folder you’ll find a file called route.ts that contains a GET route handler which uses the enableDraftAndRedirect method from the Contento Next.js SDK.
This method pulls your CONTENTO_PREVIEW_SECRET from your .env that we just updated, uses it to enable the Next.js draft mode and then redirect to the page we want to preview. This route will be called by the Contento editor when previewing content.
There is also a similar route in api > disable-draft that enables the “exit preview” button on your site.
SITE_MAIN_NAV_ID
The Minimal Starter Kit has a Navigation content type set up for you, it’s designed to allow you to manage multiple navs.
Go to the Content tab in the top menu and click into the Main Nav entry.
Now copy the ID for the entry from the right hand sidebar.
Paste this into your .env file into the SITE_MAIN_NAV_ID variable where it says your_main_nav_id:
CONTENTO_API_URL=https://app.contento.io/api/v1
CONTENTO_API_KEY=your_contento_api_key
CONTENTO_SITE_ID=your_contento_site_key
CONTENTO_PREVIEW_SECRET=your_contento_preview_secret
SITE_MAIN_NAV_ID=your_main_nav_id <------ THIS ONE
SITE_FOOTER_NAV_ID=your_footer_nav_id
* Not required in Basic Starter Kit or Marketing Website Starter Kit
SITE_FOOTER_NAV_ID
We will now do the same for the footer navigation. Go back to the Content tab in the top menu and click into the Footer Nav entry - copy the ID from there and paste it into your .env file into the SITE_FOOTER_NAV_ID variable where it says your_footer_nav_id:
CONTENTO_API_URL=https://app.contento.io/api/v1
CONTENTO_API_KEY=your_contento_api_key
CONTENTO_SITE_ID=your_contento_site_key
CONTENTO_PREVIEW_SECRET=your_contento_preview_secret
SITE_MAIN_NAV_ID=your_main_nav_id
SITE_FOOTER_NAV_ID=your_footer_nav_id <------ THIS ONE
* Not required in Basic Starter Kit or Marketing Website Starter Kit
About the code
In the app > layout.tsx file you will see that we have two variables, one for the mainNavId and one for the footerNavId. These are pulling the SITE_MAIN_NAV_ID and SITE_FOOTER_NAV_ID from your .env file that we just updated and storing them in the variables.
We then do a quick check to make sure that you have provided these IDs in your .env otherwise the server will throw an error.
Having checked that these IDs are present we then make a call to the API using the createClient helper function from your lib/contento.ts file. This time we use a different method (getContentById) to fetch only the entry you are wanting. We pass in the mainNavId and footerNavId variables and then pass those responses into the <Header /> and <Footer /> components in the html template. These components then render the header and footer parts of the page, with the navigation data populated.
This layout.tsx file provides your global layout for all pages, unless you override it with another layout.tsx file within a new route folder. It’s a great place to put your header and footer or anything that you want to appear on every page of your website.
Run the dev server
Now we have all the environment variables in place we can start your dev server using the following command:
npm run dev
This will typically start your dev server on localhost:3000, if you open this in your browser you should now be able to see the homepage for the Minimal Starter Kit.
Congratulations! You’ve now got the Minimal Starter Kit up and running 🥳
Check out the Minimal Starter Kit overview for more details on what this particular kit does, or if you’ve been following along with a different kit you can find the right guide under Guides > Starter Kits on this website.
