Guide to using Netlify CMS in local development with GatsbyJS

Every time I had to add a post or edit some data in Netlify CMS, I deployed the site to Netlify, made the change there, came back to my local setup and did a git pull. It was slow and very distracting. After a little searching, I found a better way right in the docs.

Since then: Netlify CMS was renamed Decap CMS in 2023, and the local proxy command changed with it. The steps below use the current names; the idea is the same.

Configure the CMS

Open the CMS config file, usually static/admin/config.yml in a Gatsby site, and add local_backend: true at the top level, next to your backend:

backend:
  name: git-gateway

local_backend: true

That is the only change to the config. When you open the CMS on localhost, it talks to a local proxy instead of your Git provider. On the live site, it keeps using the backend as before.

Start the local proxy

From the root of your repository, run:

npx decap-server

In 2020 this was npx netlify-cms-proxy-server. The proxy runs on port 8081 and reads and writes files in your local repository.

Start the site and edit

gatsby develop

Open http://localhost:8000/admin/, edit your content and publish. The changes are written straight to the files in your project, ready to review and commit like any other change. Your address may differ if you aren't using the default port.

Good to know

• Port 8081 taken? Set PORT in a .env file for the proxy, and give the CMS the new address with a url under local_backend (see below).
• Local only. The proxy has no authentication, so never run it on a server.
• No editorial workflow. Drafts and review states aren't supported in local mode.
• Not on Gatsby? This works the same with any static site generator: Astro, Eleventy, Hugo and others.

local_backend:
  url: http://localhost:8082/api/v1

Full details are in the Decap docs: Working with a Local Git Repository.