Netlify CMS and Gatsby plugin major release (4.x)

All PostsPosts filtered by: gatsby netlify-cms

Netlify CMS and Gatsby plugin major release (4.x)

Updated: May 1, 2018 by Tony Alves

Netlify CMS released netlify-cms-app at version 2.9.x

Gatsby released gatsby-plugin-netlify-cms 4.0.0 plugin today!

What this means for you

Once Netlify CMS version 2.9.0 landed, you can extend Netlify CMS with React as a peer dependency. This gives you the ability to use the new features of React and React hooks. Now with the Netlify CMS Gatsby plugin version 4.0.0 you can take advantage of hooks in your shared previews in your project.

Here are a couple of advantages of these new releases together:

  • Using React hooks is no longer an issue in previews
  • Smaller build bundle of the CMS in your Gatsby build
  • A more integrated coupling of NetlifyCMS into a Gatsby project

How to setup in an existing Gatsby project

yarn add netlify-cms-app gatsby-plugin-netlify-cms


npm install --save netlify-cms-app gatsby-plugin-netlify-cms

Add the Gatsby plugin to the gatsby-config.js in the site root. Create that file if it’s not already there, and add the following to register the Netlify CMS plugin:


module.exports = {
plugins: [`gatsby-plugin-netlify-cms`],

The plugin will create the Netlify CMS app and outputting it to /admin/index.html, so you’ll want to put the configuration file in that same directory (static/admin/config.yml). You can read about creating the configuration in the docs.

The Netlify CMS Gatsby starter has an example of a setup with a Gatsby project (see below).

The Gatsby docs have an entry on how to also setup Netlify CMS in a Gatsby project.

Upgrading from v3.x of gatsby-plugin-netlify-cms to v4.x

  • Upgrade to gatsby-plugin-netlify-cms@latest
  • Remove netlify-cms from the project
  • Add netlify-cms-app@latest to the project
  • Change any imports of netlify-cms to netlify-cms-app
  • If you are using Cloudinary or Uploadcare, see below
  • Use React Hooks 😁 in your previews

Try out the Netlify CMS Gatsby starter

Deploy to Netlify

Media Libraries (if not using starter) using gatsby-plugin-netlify-cms@^4.0.0

Media Libraries have been excluded from the netlify-cms-app module library. If you are planning to use Uploadcare or Cloudinary in your project, you can add them in src/cms/cms.js. Here is an example of the files to add to your project.


module.exports = {
plugins: [
resolve: 'gatsby-plugin-netlify-cms',
options: {
modulePath: `${__dirname}/src/cms/cms.js`,

For Cloudinary


import CMS from 'netlify-cms-app'
import cloudinary from 'netlify-cms-media-library-cloudinary'

For Uploadcare


import CMS from 'netlify-cms-app'
import uploadcare from 'netlify-cms-media-library-uploadcare'
© Tony Alves