Got a site? How easy is it to make content changes? Are you using a CMS? What's a CMS? How do I set up a CMS?
After this article, you'll know how to get up and running with Netlify CMS. And you'll know some tricks to make your life easier.
- Set up Netlify CMS with Next.js
- Use
netlify-cli
- Make use of Netlify CMS Beta features!
What's a CMS?
A content management system(CMS) is a convenient way for you to manage content. Think of it as a special place you visit that allows you to update your website. Update images, copy, content! It can live on the same domain or a completely different one.
What's a "headless" CMS? This means that our CMS is not coupled to a front end. It has no notion of how the content will get displayed. This is ideal. It gives portability to our content. Want to switch front-end frameworks? Cool! Drop all your content into something new. The underlying structure of what you're presenting doesn't have to change.
Why CMS?
We mentioned it there. But, "Portability". Decoupling your content from the presentation layer has the benefit of "Create once, display anywhere!". Also, "Convenience". Realized you made a typo on your site? But, you're not at your desk? Log into your CMS, make the change, hit "Publish", done! It also opens your content up for a more collaborative experience. Want to support different authors or guest posting? Create separate logins for those users.
Netlify CMS
Netlify CMS is a great option if you're new to CMS and even if you're not. It's an interesting offering that is "Git Based". That means it creates and updates the content in your Git repo. This is great if you're new to CMSs as you have the ability to see the content changes on your machine as you develop. It's very customizable too. Think custom widgets and previews.
Setting Up Netlify CMS
For today's demo, we're going to set up Netlify CMS with a Next.js site. The set up is the same though for whatever you use. If you don't have an app to use, follow along and create a Next.js site.
The prerequisites?
- Github/Gitlab/Bitbucket account
- Netlify account
- Optional – An app to integrate. Or create a demo app from the steps below.
For those in camp TL;DR , you can grab the demo app and starter kit from this repo.
Create App
Let's get started by creating an app.
yarn create next-app netlify-cms-next-starter
And for this app, I've gone ahead and pulled Tailwind in with the new shiny "JIT" compiler.
Install Netlify CMS
Then we need netlify-cms-app
.
yarn add netlify-cms-app
Set Up Admin Page
Next, we need an "admin" page. This needs to be accessible via /admin
. Different frameworks have different ways of doing this. We're using Next.js. We could drop an HTML file into public
at public/admin/index.html
or create pages/admin/index.js
.
The straight HTML would use the CDN links for Netlify CMS and looks like this.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Admin: Netlify CMS && Next.js Starter</title>
<link rel="shortcut icon" href="/assets/icons/favicon-32x32.png" />
<link rel="apple-touch-icon" href="/assets/icons/logo-192x192.png" />
<link rel="manifest" href="/manifest.webmanifest" />
<script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
</head>
<body>
<!-- Include the script that builds the page and powers Netlify CMS -->
<script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js"></script>
</body>
</html>
But, we've installed netlify-cms-app
. That means we can start up the CMS from a module.
import CMS from 'netlify-cms-app'
// Initialize the CMS object
CMS.init()
We're using Next.js though. And that means we can do something a little different with our setup.
import dynamic from 'next/dynamic'
const CMS_CONFIG = {}
const Loading = () => (
<div className="min-h-screen flex items-center justify-center">
<p className="text-gray-500 font-semibold text-xl">Loading...</p>
</div>
)
const CMS = dynamic(
() =>
import('netlify-cms-app').then((CMS) => {
CMS.init({ CMS_CONFIG })
}),
{ ssr: false, loading: Loading }
)
const Admin = () => <CMS />
export default Admin
Here, we load the netlify-cms-app
dynamically into the browser with next/dynamic
and then initialize the CMS.
Set Up CMS Config
The CMS is config-driven. We create a configuration file and this tells Netlify CMS what fields to show, what to update, etc. We need a config.yml
file that our "Admin" page has access to. There are a variety of options for configuring the CMS. Here's a basic starting point. In this config, we're creating two collections. One handles global data such as site copy for example. The other is for standalone pages. This could be the same structure for creating blog posts, etc.
backend:
name: git-gateway
branch: main
publish_mode: editorial_workflow
media_folder: "public/images"
public_folder: "/images"
collections:
- label: "Globals"
name: "globals"
files:
- label: "Site Copy"
name: "site_copy"
delete: false
create: true
file: "_data/copy.json"
fields:
- { label: "Tagline", name: "tagline", widget: "string" }
- { label: "Headline", name: "headline", widget: "string" }
- name: "standalone pages"
label: "Standalone Pages"
folder: "standalone-pages"
slug: ""
file: "standalone-pages/.mdx"
create: true
extension: mdx
format: frontmatter
fields:
- { label: "Title", name: "title", widget: "string" }
- {
label: "SEO Meta Title",
name: "metaTitle",
widget: "string",
required: false,
}
- {
label: "SEO Meta Description",
name: "metaDesc",
widget: "string",
required: false,
}
- {
label: "Social Image",
name: "socialImage",
widget: "image",
required: false,
}
- { label: "Body", name: "body", widget: "markdown" }
We've got so many options for setting up Netlify CMS. The main things here are the "backend", "media_folder", and how our collections work.
When it comes to collections, we can define the types of files, where they live, how we create the content. For example, our standalone page collection. We are stating that the files will have the MDX extension
and live under standalone-pages/
. Each field under fields
makes up the managed content for a page. In our example, we're using the string
widget for text fields. But, the body
of the file will be markdown
. Note the format
field on our collection? This tells Netlify CMS that we want to store the data in frontmatter
and follow it with the content for body
. It's worth checking out the "Configuration" docs and "Fields" docs.
Creating An Identity
If we start up our app and visit /admin
we're hit with a login screen. The CMS is working! But, we don't have any credentials to log in with.
We need an identity for authentication. You can use different auth options. But, we're going to use Netlify Identity for auth. It's the quickest to set up and will give you exposure to using Netlify Identity if you've not used it before.
Open up your Netlify dashboard and you'll want to create a "New site from Git". That's assuming you've pushed your app to a Git repository.
This will take you through your site setup. Follow the prompts and Netlify will detect your build settings for you. Note how in our case, we get the neat "Essential Next.js" build plugin installed for us.
Now we need to enable "Identity" for our site. Navigate to the "Identity" tab and hit "Enable Identity".
Go into "Settings and usage" and hit "Enable Git Gateway". It's a bit of scrolling down.
We are almost there! Now we need to invite a user to use our CMS. Hit "Invite users" and send an invite to an email address you want to use.
Once you've done that, you'll see the user in the list.
Check your email and you should see one inviting you to join the app. But, if you hit the link, you'll get directed to your hosted site and nothing will happen. That's because we need to drop the identity widget into the page and run a piece of code for it.
This only needs to doing on our root page. We need the following code to run.
if (window.netlifyIdentity) {
window.netlifyIdentity.on('init', (user) => {
if (!user) {
window.netlifyIdentity.on('login', () => {
document.location.href = '/admin/'
})
}
})
}
And this script included.
<script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
For our Next.js app, we could update our "Home" page to run the code in an effect and use next/head
to include the script.
import { useEffect, Fragment } from 'react'
import Head from 'next/head'
const Home = () => {
useEffect(() => {
if (window.netlifyIdentity) {
window.netlifyIdentity.on('init', (user) => {
if (!user) {
window.netlifyIdentity.on('login', () => {
document.location.href = '/admin/'
})
}
})
}
}, [])
return (
<Fragment>
<Head>
<title>Netlify CMS && Next.js Starter</title>
<script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
</Head>
<main className="min-h-screen flex items-center justify-center mx-auto flex-col prose">
<h1 className="text-center">Netlify CMS && Next.js Starter</h1>
</main>
</Fragment>
)
}
Re-Deploy
For the changes to take effect, we need to re-deploy our site. We can do this by pushing our changes up to our git repo. Netlify will detect the changes and re-deploy for us.
Or, we could use netlify-cli
to re-deploy our site. I recommend making use of netlify-cli
. It can improve your workflow a lot. Especially if you've already got your terminal open. To use netlify-cli
, install it first.
npm i -g netlify-cli
Once installed, login with
netlify login
And then from within your repo directory, link your repo to your site with
netlify link
Now you can build and deploy from the command line. Your build settings including plugins get pulled down for you too. It's a great way to get a deploy preview without opening a pull request too.
netlify build
netlify deploy
When you're happy with what you're deploying.
netlify build
netlify deploy --prod
Access the CMS
Once that's deployed, use your invite link from the email and you'll see a form to "Complete your signup". Create a password and you'll get logged in.
Now visit /admin
and you'll get prompted for your CMS login details. Log in and we're in! We've set up a CMS for your site with Netlify CMS.
Update Content
Now we're in the CMS, have a poke around and explore what you can do. For example, upload an image or change the content in one of your collections. Here I've changed the content under a "Tagline" field in our "Globals" collection. When we're ready to push the changes, we hit "Save", update the status to "Ready", and then hit "Publish".
Next, it's a waiting game. Wait for the changes to get pushed. Pull them down to your repo in your terminal and you'll see that in our case _data/copy.json
has updated. This was the path we defined in our config.yml
file.
Now you can integrate your content any way you like with your frontend. For example, in our demo app, I've added an import path for _data
. And I've updated the "Home" page to display the headline and tagline.
import { useEffect, Fragment } from 'react'
import Head from 'next/head'
import copy from '@data/copy.json'
const Home = () => {
useEffect(() => {...}, [])
return (
<Fragment>
<Head>
<title>Netlify CMS && Next.js</title>
<script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
</Head>
<main className="min-h-screen flex items-center justify-center mx-auto flex-col prose">
<h1 className="text-center">{copy.headline}</h1>
<h2>{copy.tagline}</h2>
</main>
</Fragment>
)
}
At this stage, you've got a working CMS for your app. Explore the docs and manage your content any way you like. But, we're not quite done yet. Let's improve this setup.
Local Backend
We've got a working CMS. But, the workflow could be slow. Especially if we're feeling out what we're going to put in our CMS. We haven't got time to keep deploying, making changes in the CMS, and waiting for things to get pushed to Git. Builds take time and they'll use up your build minutes on Netlify.
To get around this we're going to use a Beta feature, local_backend
. In fact, if you've been using Netlify CMS already, this trick might help you out a bunch if you didn't know about it.
To use local_backend
, add it to our config.yml
file.
local_backend: true
backend:
name: git-gateway
branch: main
publish_mode: editorial_workflow
media_folder: "public/images"
public_folder: "/images"
And then we have one more step. We need to use netlify-cms-proxy-server
when we are developing. We can update our dev
script to accommodate this.
"scripts": {
"dev": "npx netlify-cms-proxy-server & next dev",
}
Run our dev server and visit /admin
. We're in! No log-in screen required. Make some content changes, hit publish, and the content gets updated in your directory. Awesome. This improves our workflow tenfold. No more waiting.
This is all possible because of netlify-cms-proxy-server
which creates a local unauthenticated server. This is what the CMS runs on when we use local_backend
. You can configure local_backend
in different ways. And you don't have to worry if you deploy a config.yml
file with local_backend
on.
But, if that doesn't sit right with you, you can write a node script that you run when running your dev server.
Here's a script you can use that copies your config.yml
to the public
directory on change. It uses chokidar
to watch the file changes and logs any activity with pino
.
const chokidar = require('chokidar')
const logger = require('pino')({ prettyPrint: true })
const fs = require('fs')
// Write file to public/config.yml
const writeConfig = () => {
logger.info('Updating Netlify CMS Config')
const CONFIG = fs.readFileSync('./admin/config.yml', 'utf-8')
fs.writeFileSync(
`${process.cwd()}/public/config.yml`,
`local_backend: true\n${CONFIG}`,
'utf-8'
)
}
// Set up Netlify CMS Config Watching
logger.info('Setting up Netlify CMS config watch')
chokidar.watch(`${process.cwd()}/admin/config.yml`).on('change', writeConfig)
// Write on script run so it's there
writeConfig()
In this script, we are copying the config and appending the local_backend
option. This means we no longer need a committed version of config.yml
inside public
. In the demo app, I've moved it into an admin
directory along with the watch script.
To have that run at dev time, we can update our package.json
script to run this alongside netlify-cms-proxy-server
.
{
"scripts": {
"dev": "npx netlify-cms-proxy-server & next dev & node admin/config-watcher.js"
}
}
That's It!
That's how to get up and running with a "Headless" CMS. In this case, Netlify CMS. It's a neat solution and a great entry point if you've not set up a CMS for yourself before.
I'd recommend setting up a CMS for your sites. Especially your personal portfolio sites. How about trying Netlify CMS? Get set up, have a look around the docs, customize it to your needs!
Want to try it out with Next.js? Check out the demo repository that's set up with Tailwind and use that as a starting point.
As always, thanks for reading. Wanna know more? Wanna see something else? Come find me on Twitter!
Stay awesome! ʕ •ᴥ•ʔ
Top comments (2)
Very cool! Thanks for sharing, Jhey!
Great article! Thank you!