Next.js and Content Management Systems (CMS): A Beginner’s Guide to Headless CMS Integration

Written by

learnmodernjavascript

in

In the ever-evolving landscape of web development, the need for flexible, scalable, and content-rich websites has driven developers to explore innovative solutions. One such solution is the integration of a Content Management System (CMS) with a modern JavaScript framework. This tutorial delves into the powerful synergy between Next.js, a popular React framework for building web applications, and Headless CMS platforms. We will guide you through the process of integrating a Headless CMS into your Next.js project, empowering you to create dynamic, content-driven websites with ease.

Why Combine Next.js and a Headless CMS?

Traditional CMS platforms, while offering user-friendly content editing interfaces, often come with limitations in terms of customization and performance. They can be monolithic, making it difficult to decouple the content from the presentation layer. This is where Headless CMS platforms shine. A Headless CMS focuses solely on content storage and delivery via APIs, leaving the presentation layer entirely in the hands of the developer. Next.js, with its focus on performance, SEO optimization, and developer experience, is an ideal front-end framework to consume this content.

Here’s why you should consider using Next.js with a Headless CMS:

  • Performance: Next.js offers features like Static Site Generation (SSG) and Server-Side Rendering (SSR), resulting in fast-loading websites.
  • SEO: Next.js is SEO-friendly, making it easier for search engines to crawl and index your content.
  • Flexibility: Headless CMS platforms provide flexibility in content modeling and allow you to choose your preferred front-end technology (Next.js in this case).
  • Content Management: Headless CMS platforms offer intuitive interfaces for content creators to manage content without needing to know any code.
  • Scalability: Decoupling the front-end from the back-end allows for independent scaling of both.

Choosing a Headless CMS

There are numerous Headless CMS platforms available, each with its strengths and weaknesses. Some popular choices include:

  • Contentful: A cloud-based CMS known for its flexibility and ease of use.
  • Strapi: An open-source, self-hosted CMS that provides a high degree of customization.
  • Sanity: A real-time content platform with a flexible data structure and a powerful editing experience.
  • Prismic: A CMS focused on content reuse and structured content.
  • Ghost: A CMS optimized for blogging and publishing.

For this tutorial, we will use Contentful. It offers a generous free tier and a straightforward API, making it an excellent choice for beginners. However, the concepts presented here can be easily adapted to other Headless CMS platforms.

Setting Up a Contentful Space

If you don’t already have a Contentful account, sign up for a free one at Contentful. Once you’re logged in, create a new space. A space is where you’ll store your content. Within your space, you’ll need to define a content model. A content model describes the structure of your content. For example, if you’re building a blog, you might have a content type called “Blog Post” with fields like “Title,” “Body,” “Author,” and “Publish Date.”

Here’s a step-by-step guide to setting up a basic content model in Contentful:

  1. Create a Content Type: In your Contentful space, navigate to the “Content model” section and click “Create content type.”
  2. Define Fields: Add fields to your content type. For a simple blog post, you might add the following fields:
    • Title: Text (short text)
    • Slug: Text (short text) – This is important for creating unique URLs for each post.
    • Body: Rich Text (this will allow you to format your content in the CMS)
    • Author: Text (short text)
    • Publish Date: Date and time
    • Featured Image: Media (single)
  3. Save the Content Type: Once you’ve added all the necessary fields, save your content type.
  4. Create Content Entries: Go to the “Content” section and click “Add entry” to create your first blog post. Fill in the fields you defined in your content type.
  5. Publish Your Content: Once you’ve created your content entries, publish them. Only published content is accessible through the Contentful API.

After creating some content, you’ll need the following from your Contentful space:

  • Space ID: Found in Settings -> General Settings.
  • Content Delivery API Access Token: Found in Settings -> API keys.

Creating a Next.js Project

Now, let’s create a new Next.js project. Open your terminal and run the following command:

npx create-next-app@latest nextjs-contentful-blog --typescript --eslint

This command creates a new Next.js project named “nextjs-contentful-blog” with TypeScript and ESLint pre-configured. Navigate into your project directory:

cd nextjs-contentful-blog

Next, install the Contentful JavaScript client:

npm install contentful

Connecting to Contentful

Create a file named `.env.local` in the root of your project. This file will store your Contentful credentials. Add the following lines, replacing the placeholders with your actual Space ID and Content Delivery API Access Token:

CONTENTFUL_SPACE_ID=YOUR_CONTENTFUL_SPACE_ID
CONTENTFUL_ACCESS_TOKEN=YOUR_CONTENTFUL_ACCESS_TOKEN

Important: Never commit your `.env.local` file to your Git repository. It contains sensitive information.

Next, create a file called `lib/contentful.ts` to handle the Contentful API calls. This file will contain the logic to fetch content from your Contentful space. Add the following code:

import { createClient } from 'contentful';

const client = createClient({
 space: process.env.CONTENTFUL_SPACE_ID!,
 accessToken: process.env.CONTENTFUL_ACCESS_TOKEN!,
});

export async function getAllPosts() {
 try {
 const entries = await client.getEntries({
 content_type: 'blogPost',
 order: '-fields.publishDate', // Order by publish date, descending
 });
 return entries.items;
 } catch (error) {
 console.error('Error fetching posts:', error);
 return [];
 }
}

export async function getPostBySlug(slug: string) {
 try {
 const entries = await client.getEntries({
 content_type: 'blogPost',
 'fields.slug': slug, // Filter by slug
 });
 return entries.items[0]; // Assuming slug is unique
 } catch (error) {
 console.error('Error fetching post by slug:', error);
 return null;
 }
}

export async function getFeaturedImage(id:string){
  try{
    const asset = await client.getAsset(id);
    return asset;
  } catch (error){
    console.error('Error fetching featured image:', error);
    return null;
  }
}

This code does the following:

  • Imports the `createClient` function from the `contentful` package.
  • Creates a Contentful client using your Space ID and Access Token from your `.env.local` file. The `!` after `process.env.CONTENTFUL_SPACE_ID` and `process.env.CONTENTFUL_ACCESS_TOKEN` is a non-null assertion operator, telling TypeScript that these environment variables are guaranteed to be defined.
  • Defines an `getAllPosts` function that fetches all blog posts from Contentful. It specifies the `blogPost` content type and orders the posts by publish date in descending order.
  • Defines a `getPostBySlug` function that fetches a single blog post by its slug.
  • Defines a `getFeaturedImage` function that fetches the featured image by its ID.

Fetching and Displaying Blog Posts

Now, let’s create a page to display a list of blog posts. Open the `pages/index.tsx` file and replace its contents with the following code:

import type { NextPage } from 'next';
import { getAllPosts } from '../lib/contentful';
import Link from 'next/link';
import Image from 'next/image';

interface Post {
 fields: {
 title: string;
 slug: string;
 publishDate: string;
 featuredImage: {sys: {id: string}};
 };
}

interface Props {
 posts: Post[];
}

const Home: NextPage<Props> = ({ posts }) => {
 return (
 <div className="container mx-auto py-8">
 <h1 className="text-3xl font-bold mb-4">Blog Posts</h1>
 <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
 {posts.map((post) => (
 <div key={post.fields.slug} className="bg-white rounded-lg shadow-md overflow-hidden">
 <Link href={`/posts/${post.fields.slug}`}>
 <a>
 <Image
 src={`https:${post.fields.featuredImage?.fields?.file?.url}`}
 alt={post.fields.title}
 width={600}
 height={400}
 className="w-full h-48 object-cover"
 />
 </a>
 </Link>
 <div className="p-4">
 <Link href={`/posts/${post.fields.slug}`}>
 <a className="text-xl font-semibold hover:text-blue-600">{post.fields.title}</a>
 </Link>
 <p className="text-gray-600 text-sm mt-2">{new Date(post.fields.publishDate).toLocaleDateString()}</p>
 </div>
 </div>
 ))} 
 </div>
 </div>
 );
};

export async function getStaticProps() {
 const posts = await getAllPosts();
 return {
 props: { posts },
 };
}

export default Home;

This code does the following:

  • Imports `getAllPosts` from `../lib/contentful`.
  • Defines a `Post` interface to provide type safety.
  • Uses `getStaticProps` to fetch blog posts at build time. This is the optimal approach for static content.
  • Maps over the fetched posts and renders each one as a card with a title, publish date, and a link to the individual post page.

You may need to install the following packages:

npm install next/image

Next, let’s create a dynamic route for individual blog posts. Create a file named `pages/posts/[slug].tsx`. This file uses the file-based routing provided by Next.js.

import type { GetStaticProps, GetStaticPaths, NextPage } from 'next';
import { getAllPosts, getPostBySlug } from '../../lib/contentful';
import { documentToReactComponents } from '@contentful/rich-text-react-renderer';
import Image from 'next/image';

interface Post {
 fields: {
 title: string;
 body: any;
 publishDate: string;
 author: string;
 featuredImage: {
 sys: {
 id: string;
 };
 };
 };
}

interface Props {
 post: Post;
}

const Post: NextPage<Props> = ({ post }) => {
 if (!post) {
 return <p>Loading...</p>;
 }

 return (
 <div className="container mx-auto py-8">
 <h1 className="text-3xl font-bold mb-4">{post.fields.title}</h1>
 <p className="text-gray-600 text-sm mb-4">Published on {new Date(post.fields.publishDate).toLocaleDateString()} by {post.fields.author}</p>
 <Image
 src={`https:${post.fields.featuredImage?.fields?.file?.url}`}
 alt={post.fields.title}
 width={800}
 height={500}
 className="w-full mb-4 object-cover"
 />
 <div className="prose">
 {documentToReactComponents(post.fields.body)}
 </div>
 </div>
 );
};

export const getStaticPaths: GetStaticPaths = async () => {
 const posts = await getAllPosts();
 const paths = posts.map((post) => ({
 params: {
 slug: post.fields.slug,
 },
 }));

 return {
 paths,
 fallback: false,
 };
};

export const getStaticProps: GetStaticProps = async ({ params }) => {
 const { slug } = params as {
 slug: string;
 };
 const post = await getPostBySlug(slug);

 return {
 props: {
 post,
 },
 };
};

export default Post;

This code does the following:

  • Imports `getPostBySlug` from `../../lib/contentful`.
  • Uses `getStaticPaths` to generate the paths for all blog posts at build time. This ensures that each blog post has a unique URL.
  • Uses `getStaticProps` to fetch the data for a specific blog post based on the slug.
  • Renders the blog post content, including the title, publish date, author, and body. The body is rendered using the `documentToReactComponents` function from the `@contentful/rich-text-react-renderer` package, which is necessary to render rich text content from Contentful.

You will need to install the following package:

npm install @contentful/rich-text-react-renderer

Styling with Tailwind CSS (Optional)

For styling, we’re using Tailwind CSS. If you did not choose Tailwind when creating your project, you’ll need to install it and configure it. Follow the instructions on the Tailwind CSS documentation. This is what your `tailwind.config.js` might look like:


/** @type {import('tailwindcss').Config} */
module.exports = {
 content: [
 './app/**/*.{js,ts,jsx,tsx,mdx}',
 './pages/**/*.{js,ts,jsx,tsx,mdx}',
 './components/**/*.{js,ts,jsx,tsx,mdx}',

 // Or if using `src` directory:
 './src/**/*.{js,ts,jsx,tsx,mdx}',
 ],
 theme: {
 extend: {

 },
 },
 plugins: [],
}

The code examples above already incorporate Tailwind CSS classes for styling. You can customize the styles to match your design preferences.

Common Mistakes and How to Fix Them

  • Incorrect Environment Variables: Make sure your `.env.local` file is correctly configured with your Contentful Space ID and Access Token. Double-check for typos and ensure the file is in the root of your project.
  • API Rate Limits: Contentful has API rate limits. If you’re fetching a large number of entries, consider implementing pagination or caching to avoid exceeding these limits.
  • Incorrect Content Type IDs: Ensure that the content type IDs used in your code match the content type IDs in your Contentful space.
  • Missing Dependencies: Make sure you have installed all the necessary dependencies, including `contentful` and `@contentful/rich-text-react-renderer`.
  • Rendering Rich Text: Remember to use the `documentToReactComponents` function to render rich text content from Contentful.
  • Image Optimization: Use Next.js’s Image component to optimize images for performance.

Key Takeaways

In this tutorial, we’ve walked through the process of integrating a Headless CMS (Contentful) with Next.js. We covered the following:

  • Setting up a Contentful space and defining a content model.
  • Creating a Next.js project and installing the necessary dependencies.
  • Connecting to Contentful using environment variables.
  • Fetching content from Contentful using the Content Delivery API.
  • Displaying blog posts on your website.
  • Implementing dynamic routing for individual blog posts.
  • Styling your website with Tailwind CSS.

By following these steps, you can create a dynamic and content-rich website with a modern JavaScript framework, a Headless CMS, and a focus on performance and SEO.

FAQ

Q: Can I use a different Headless CMS?

A: Yes! While this tutorial uses Contentful, the general concepts and techniques can be applied to other Headless CMS platforms like Strapi, Sanity, or Prismic. The main difference will be in the API calls and the way you structure your content model.

Q: How do I handle images from Contentful?

A: When you define a field of type “Media” in your Contentful content model, you can access the image data through the Contentful API. You can then use the `next/image` component to optimize and display the images on your Next.js website. Make sure to use the correct image URL from the Contentful API response.

Q: How can I preview content before publishing it?

A: Contentful offers a preview API that allows you to fetch draft content. You can integrate this API into your Next.js application to enable content preview functionality. This usually involves using a different access token for the preview API and modifying your API calls to fetch draft content.

Q: How can I deploy my Next.js application with Contentful?

A: You can deploy your Next.js application to platforms like Vercel, Netlify, or AWS. These platforms offer easy deployment processes and often provide built-in support for environment variables, which is important for storing your Contentful credentials. Make sure to set your environment variables in the deployment platform’s settings.

The integration of Next.js and a Headless CMS like Contentful offers a powerful and flexible approach to web development. It allows you to build highly performant, SEO-friendly websites with a clean separation between content and presentation. By mastering the concepts and techniques outlined in this tutorial, you’re well on your way to creating modern, dynamic, and content-driven web applications that provide a superior user experience and are easy for content creators to manage. With the right combination of tools and a solid understanding of the underlying principles, you can build websites that not only look great but also perform exceptionally well and adapt to the ever-changing demands of the web.

More posts