Pros/Cons following Netlify Docs vs setting things up like they are in the one-click installs?

I notice that in the one click installs, yarn/babel and almost every other front-end framework in existence is used to compile and host an instance of the NetlifyCMS along with the static website, vs what the docs say on NetlifyCMS website, where the js is all external.

What are the pros and cons to each method? Which is simpler? I am guessing the option where external js is called.

In which cases would it be right to go for the more complicated architecture?

There are just two different approaches, it depends on your setup which makes the most sense. The docs outline both, install through npm and CDN. It pretty much comes down to wether you use a package manager or not. There are also a bunch of plugins out there that make setting up the CMS slightly easier, but it’s up to you if you use them or not.


Would NetlifyCMS and it’s dependencies be installed on each build? If not, are the files listed below only meant for a dev install?

  • gulpfile.babel.js
  • package.json
  • renovate.json
  • webpack.conf.js
  • yarn.lock
  • and the stuff located in src

My current understanding is that all of this above gets used to generate the JS and css that is needed to support NetlifyCMS. Isn’t this better to be managed in a different repo. One that creates the build image?

Then you would just need minimal templates in your static site repo that builds /admin/index.html and the dependent js/css.

Duplicating all that boilerplate code to each of one’s static site repos is just ugly, and if it is parsed on each build, wouldn’t that affect page generation times?

I am still learning the ropes here, so please point me in the right direction if I have got it wrong. I guess I need the most ‘backend dev’ approach (which is what attracted me to Hugo, I didn’t need a knowledge of front end to get on with generating a static site.

For now I am going with the simplified way of installing. Which if I understand correctly, all the js artifacts are pre-built and hosted on a CDN?

1 Like

To add to @tomrutgers awesome answer, there is a good path to knowing when to use an npm workflow into your project. I will take a stab at the reasons/recommendations.

Use script import of netlify-cms

This method is the default method and easiest to get a simple cms up and running on a static site using the pre-built bundle from a CDN or download and add to you static assets.

<!doctype html>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Content Manager</title>
  <!-- Include the script that builds the page and powers Netlify CMS -->
  <script src="^2.0.0/dist/netlify-cms.js"></script>


  • Simple setup
  • Don’t have to manage a bundle in your project


  • Typically harder to add previews
  • If a registered widget is added, it must have a UMD build or global to access the widget from a named global
  • The external widget must have the correct external peer deps for use cases using React with hooks

Using a package manager (npm) to extend

This method is a more advanced method to extend the CMS using a bundler workflow like webpack or rollup. Usually used by projects that allow a bundle to be created by importing the netlify-cms-app and already have a React workflow.


  • Can extend the CMS within a React app reusing existing components from your project
  • Potentially smaller bundle. (media libraries are not included in netlify-cms-app)
  • Easier to extend the CMS if you are a React developer
  • Allows for importing of more complex config files that can be managed


  • More complicated setup
  • The CMS is still not 100% a React component, so must be aware it uses should be bundled as a standalone React SPA.
  • Requires some knowledge of React
  • Requires nodejs workflow to be able to setup a bundle to be used in your static site
  • Learning curve for the beginner and could confuse even an advanced developer due to complexity of the API
  • Some API’s are in beta and could have breaking changes down the road, but most changes should be backward compatible.

@dnk8n All your points are valid.

There is an easy path to creating a create-react-app using a starter like I setup here. You will notice it imports netlify-cms-app and extends the cms to a valid build.

There is no easy answer to this question for all cases.

In the case of Hugo, you would probably create a stand alone cms bundle and import it into your static assets for the project.

As an example in a Gatsby app you want to be able to reuse components for previews. Gatsby has a plugin for the CMS to be bundled separately. It does add to the build times in a continuous workflow, but the re-use of preview components in the site is a trade-off.


Thanks for the very elaborate follow-up @talves!

1 Like