How to Implement Netlify CMS With Next.js
Tags: react, nextjs, cms, tutorial
Published: 2020-11-30 09:28:52


#### _Manage the content of your Next.js apps through a free Git-based CMS_

If you’re starting a new React project, you might want to consider [Next.js](https://nextjs.org/) and [Netlify CMS](https://www.netlifycms.org/). In this article, we take a look at why this would be a great choice and walk through the process of setting up a new project using these technologies.

## Why Next.js?

As I stated in [a previous article](https://medium.com/better-programming/how-to-set-up-next-js-with-typescript-5f912766c88):

> “There are many important details you need to consider when you start a new project with React. Your code has to be bundled using a bundler like webpack and transformed using a compiler like Babel.
>
> [Create React App](https://reactjs.org/docs/create-a-new-react-app.html) can be a nice tool to handle this for you and give you a massive head start, but what about code-splitting, pre-rendering for performance, and SEO or server-side rendering?
>
> To build a complete React application, you need more than CRA provides you with. You can save yourself some time by using Next.js, a React framework that provides a solution to all of these problems.”

If you want to read more about CRA vs. Next.js, check out [Stack choices: Create React App vs Next.js](https://codeburst.io/stack-choices-create-react-app-vs-next-js-f0f3c4db7083).

## Why Netlify CMS?

[Netlify CMS](https://www.netlifycms.org/) is an open-source Git-based content management system. It is based on client-side JavaScript and handles content updates directly in Git. Because all content is just stored in your Git repository, you don’t need to have anything hosted on a server. It’s completely free and a great fit to combine with Next.js to build landing pages or blogs that are manageable through a nice UI.

## Let’s Begin

Let’s begin building our landing page with some basic text to get familiar with Netlify CMS. You can find the source code of this part of the tutorial [on GitHub](https://github.com/jakeprins/nextjs-netlify-cms) or check out [serverless.page](http://serverless.page/) for a complete boilerplate that also includes features like authentication and billing.

### Set up your project

You can start by creating a new Next.js project with `npx create-next-app`. In this example, we are going to use TypeScript. You can follow [this tutorial](https://medium.com/better-programming/how-to-set-up-next-js-with-typescript-5f912766c88) on how to set up Next.js with Typescript.

## Using Markdown Files for Our Content

Netlify CMS works with markdown files, and it’s a great way to manage the content of your landing page or blog. Let’s begin by creating a markdown file that will have some data we want to show on our home screen.

Make a `content` directory that will hold all our markdown files. Next, create a `pages` directory and a markdown file called `content/pages/home.md`. This file will hold the data that we want to show on our home page. Let’s start by adding a title, description, and image for the “hero” section of our landing page:

```
---
hero_title: Build a SaaS faster with React
hero_description: Serverless SaaS is aiming to be the perfect starting point for your next React app to build full-stack SaaS applications. Visit serverless.page for more info.
---
```

Next, we need to tell webpack how to load markdown files. Let’s use `frontmatter-markdown-loader` for this. Start by installing that package as a dev dependency:

```
yarn add frontmatter-markdown-loader -D
```

Next, create a new `next.config.js` file at the root of your project with the following content:

### Create the home page

Cool, now let’s add some code to the index page to make it our home page.

In `pages/index.tsx`, add the following:

Let’s have a look at what’s going on here. The most important part is the exported `getStaticProps` function. If you export an `async` function called `getStaticProps` from a page, Next.js will pre-render this page at build time using the props returned by `getStaticProps`.

On our page, we import our markdown file called `home.md` and pass it a `content` prop to our component. Our home page can now use the `hero_title` and `hero_description` attributes of the markdown file.

Let’s try it out and see if it’s working:

```
yarn dev
```

You should see your amazing hero section, ready to be styled and managed with your upcoming CMS.

## Implement Netlify CMS

There are different ways to add Netlify CMS to your project. We are going to use the official npm package:

```
yarn add netlify-cms-app
```

### Add the configuration

Before we can initialize our CMS, we need to create a config file. Create a `cms` directory at the root of your project and paste the following configuration to your `cms/config.js`:

```js
export default {
  cms_manual_init: true,
  backend: {
    name: 'github',
    repo: 'yourname/your-github-repo-name',
    branch: 'main',
  },
  media_folder: 'public/img',
  public_folder: 'img',
  collections: [
    {
      name: 'pages',
      label: 'Pages',
      files: [
        {
          label: 'Home',
          name: 'home',
          file: 'content/pages/home.md',
          fields: [
            {
              label: 'Hero Title',
              name: 'hero_title',
              widget: 'string',
            },
            {
              label: 'Hero Description',
              name: 'hero_description',
              widget: 'markdown',
            },
          ],
        },
      ],
    },
  ],
};
```

Netlify CMS has different options on how to handle authentication. We are going to use this config file to tell Netlify CMS that we want to use the GitHub for this. For repositories stored on GitHub, the `github` back end allows CMS users to log in directly with their GitHub account. Note that all users must have push access to their content repository for this to work.

If you haven’t done already, now would be a good time to [create your repository on GitHub](https://github.com/new), add the name of your repo to the config file, and push your code to GitHub. Go ahead — I’ll wait.

Good, but before we move on, let’s take a look at the most important setting of our configuration: the `collections`. This determines how content types and editor fields in the UI generate files and content in your repository.

Inside `collections`, we create a `pages` collection that has some settings for the `home` page. For now, we only added the `hero_title` and `hero_description` fields. You can set which [widget](https://www.netlifycms.org/docs/widgets/#header) to use for the given property.

You can read about all other configuration options [in the documentation](https://www.netlifycms.org/docs/configuration-options).

### Initialize the CMS

Next, let’s create an admin page for our CMS. Add the following code to `pages/admin.tsx`:

```tsx
import dynamic from 'next/dynamic';
import config from '../cms/config';

const CMS = dynamic(
  () =>
    import('netlify-cms-app').then((cms) => {
      cms.init({ config });
    }),
  { ssr: false, loading: () => <p>Loading...</p> }
);

const AdminPage: React.FC = () => {
  return <CMS />;
};

export default AdminPage;
```

Now you should be able to navigate to [http://localhost:3000/admin](https://localhost:4202/) and see a GitHub login button. Hit the button and see your nice new CMS!

<img alt="Blank CMS" class="t u v hn aj" src="https://miro.medium.com/max/700/1*sCq_bD6q9UjrCg-YhKpL_A.png" width="1058" height="369"/>

### Try it out

Cool, now try it out! Select “Home” and you will see the edit page. You can edit the `hero_title` and `hero_description` properties and click the `publish` button. When you publish, Netlify CMS is making a commit to your repository with the changes you just made. You can take a look at the last commit after you have published some changes.

Now, all you have to do is `git pull` to get those changes locally and navigate back to [http://localhost:3000/](http://localhost:3000/). You will see that the home page contains your changes. Sweet!

## Adding Images

Most hero sections contain a pretty image. Let’s use the `image` widget to add an image to our hero section. Go to your `cms/config.js` file and add the following object to the `fields` array:

```js
{
  label: 'Hero Image',
  name: 'hero_image',
  widget: 'image'
}
```

Next, we could simply add an image to our `public/img` folder and add it to our `home.md`, but to demonstrate how Netlify CMS works, we are going to use the CMS to do it.

First, we need to upload an image to our integrated media library. On the dashboard of the CMS, click the “Media” link in the top navbar and upload an image. After that, navigate to the edit screen of the home page.

You should now see the added `hero_image` field with a button that says, “Choose an image.” You can now select your uploaded image and publish the changes.

Great, we should now have a new commit to our repo with the new changes. If our application was already in production, we could see the changes live, but since we want to see these changes locally, we need to first pull them from GitHub.

After you have run `git pull`, there is really only one thing left to do, which is adding the image to our home page:

```tsx
...
<img src={attributes.hero_image} alt='hero image' />
...
```

Now, run `yarn dev` and go to [http://localhost:3000/](http://localhost:3000/) to see your added image!

## Conclusion

Netlify CMS is a very useful library you can add to your Next.js apps. It’s just a client-side React application, and it uses Git to store content in your own repository. This has some nice benefits: You don’t need to host your CMS separately and it fits perfectly in your Git workflow. This is great for managing the content of a landing page or blog post.

If you are looking for a complete boilerplate, check out [serverless.page](http://serverless.page/).

## Next Steps

We have covered a lot in this tutorial, but we have only seen the basics of how Netlify CMS works in a Next.js application. There is a lot more we can do! Stay tuned for upcoming articles to continue our work with:

- A blog
- More widgets for managing content
- Styling and CMS previews
- Customizing with additional configuration settings

View the source code of this tutorial [on GitHub](https://github.com/jakeprins/nextjs-netlify-cms).

Thanks for reading! You can find me on Twitter ([@jakeprins_nl](https://twitter.com/jakeprins_nl)) or read more at [jakeprins.com/blog](https://jakeprins.com/blog).