![\"Deploy](\"https://www.netlify.com/img/deploy/button.svg\")
Netlify CMS is an extensible app written in, and bundled with, React. The most common extension is the custom preview template, which allows the preview on the right side of the editor to show what the site will actually look like as you type. These preview templates are also written in React.
\nPreview templates and other extensions can only use the Netlify CMS bundled copy of React via the createClass() method that Netlify CMS exports. Since React components are most often written in JSX and transpiled through a build system, most developers won't want to use this method, so the preview templates are created with a separate copy of React.
This means that Netlify CMS has two instances of React running at once.
\nBut everything still worked - until React Hooks was released.
\nBefore Hooks, multiple instances of React could work on the same DOM, although it was warned against and technically not supported. React Hooks changed this by throwing an error if multiple instances are detected. When developers started using hooks in their Netlify CMS previews and widgets, their applications stopped working ðŸ˜
\nnetlify-cms-appIn the past, the netlify-cms npm package was the only way to run Netlify CMS - it's a \"batteries included\" distribution that runs as-is, bringing along React and a number of default extensions (widgets, backends, etc).
As of Netlify CMS 2.9.0, a new netlify-cms-app package is provided as a slimmed down alternative to netlify-cms. It still includes most default extensions, but excludes some of the heavier ones, like media libraries for external providers.
Most importantly, it does not include react or react-dom, requiring them instead as peer dependencies. This allows Netlify CMS and any extensions to all use a single instance of React and React DOM. As a bonus, the netlify-cms-app bundle is a bit smaller than netlify-cms.
If you're building your site with Gatsby, skip this section. For all others, you'll want to:
\nnetlify-cms if you're already using itnetlify-cms-appreact and react-domnpm uninstall netlify-cms\nnpm install netlify-cms-app react react-domThat's it! Now Netlify CMS will use the version of React that you provide.
\nGatsby provides transpiling and bundling with Babel and Webpack, and accepts plugins to support various JavaScript dialects, e.g., TypeScript. If a developer sets up their Gatsby site to be written a certain way, they'll want any CMS customization code to be written the same way. The problem is that Netlify CMS is a standalone app that would typically live in Gatsby's static directory, and Gatsby doesn't really have a way to handle a secondary entry point for the CMS for outputting a dedicated bundle.
For this reason, we support an official Gatsby plugin, gatsby-plugin-netlify-cms, which bundles preview templates and other Netlify CMS extensions using the same Babel and Webpack configuration as the Gatsby site itself.
The recent 4.0.0 release of gatsby-plugin-netlify-cms is the first to use netlify-cms-app and enable the use of React Hooks in Netlify CMS previews/widgets for Gatsby projects.
If you want to start a new site now, or would like to see an example, check out gatsby-starter-netlify-cms - it provides a great starting point and implements all of the remaining steps in this post.
You can deploy it to Netlify right now with one click!
\n
If you're already using gatsby-plugin-netlify-cms, you'll want to:
netlify-cms dependencynetlify-cms-appnpm upgrade gatsby-plugin-netlify-cms@^4.0.0\nnpm uninstall netlify-cms\nnpm install --save netlify-cms-appNote that you'll already have React and React DOM installed in your Gatsby project, so no need to do that here.
\nIf you're not already using gatsby-plugin-netlify-cms with your Gatsby project, you can install it and netlify-cms-app via npm (or your package manager of choice):
npm install --save netlify-cms-app gatsby-plugin-netlify-cmsYou'll also need to register the plugin in 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:
// gatsby-config.js\n\nmodule.exports = {\n plugins: [`gatsby-plugin-netlify-cms`],\n}The plugin will create the Netlify CMS app and output it to /admin/index.html on your site. The CMS will look for your configuration to be in the same directory on your live site, at /admin/config.yml, so you’ll want to place the configuration file in the static directory of your repo at static/admin/config.yml. You can also configure Netlify CMS with JavaScript. Read more about configuring the CMS in our docs, or check out the Gatsby / Netlify CMS integration guides in both our docs and theirs.
netlify-cms-appThe Netlify CMS media library extensions for Cloudinary and Uploadcare are not included in netlify-cms-app. If you're using netlify-cms-app, you'll need to register media libraries yourself.
Note: if you're using gatsby-starter-netlify-cms, the media libraries are registered within the starter itself.
import CMS from 'netlify-cms-app';\n\n// You only need to import the media library that you'll use. We register both\n// here for example purposes.\nimport uploadcare from 'netlify-cms-media-library-uploadcare';\nimport cloudinary from 'netlify-cms-media-library-cloudinary';\n\nCMS.registerMediaLibrary(uploadcare);\nCMS.registerMediaLibrary(cloudinary);For more information about the media libraries, refer to the docs.
\n\ngatsby-plugin-netlify-cms@^4.0.0In addition to calling registerMediaLibrary() as mentioned above, make sure to provide the path to your CMS customization entry point to Gatsby via gatsby-config.js:
// gatsby-config.js\n\nmodule.exports = {\n plugins: [\n {\n resolve: 'gatsby-plugin-netlify-cms',\n options: {\n modulePath: `${__dirname}/src/cms/cms.js`,\n },\n },\n ]\n}If you run into a problem or need help, open an issue on GitHub or chat with our community!
"}},"pageContext":{"slug":"/blog/2019/07/netlify-cms-gatsby-plugin-4-0-0"}}}