Decap CMS Proxy Server

3.7.0 · active · verified Tue Apr 21

Decap CMS Proxy Server (`decap-server`) is a lightweight Node.js Express server designed to facilitate local development with Decap CMS, particularly when using `git-gateway` or `proxy` backends. It acts as an unauthenticated intermediary between your local Decap CMS instance and a Git repository (e.g., GitHub, GitLab), allowing content changes to be saved directly to your local files during development without needing a live backend connection. The current stable version is 3.7.0, with releases typically following the frequent cadence of the broader Decap CMS project (major, minor, and patch releases occurring regularly). Its key differentiator is simplifying the local development workflow for Decap CMS by abstracting Git operations, making it an essential tool for local content authoring and testing.

Common errors

```
listen EADDRINUSE: address already in use :::8081
```
cause The default port 8081 is already being used by another application on your system.

fix Specify a different port by creating a `.env` file in your project root with `PORT=XXXX` (e.g., `PORT=8082`) and then running `npx decap-server`.
```
Failed to load entry: API Error
```
cause This often indicates that the `decap-server` could not properly interact with your Git repository via the GitHub/GitLab API. Common causes include: a) specified folders (e.g., `media_folder`) do not exist in the repository, b) the personal access token (PAT) used by the underlying `decap-cms` backend has insufficient permissions (e.g., missing 'repo' scope for GitHub), or c) an incorrect repository path in your `config.yml`.

fix 1. Ensure all configured `media_folder` and collection `folder` paths actually exist in your Git repository. Create empty `.gitkeep` files in these folders if necessary. 2. Verify that the Personal Access Token (PAT) used by your Git backend (often configured via the `base_url` or `auth_endpoint` settings that the proxy handles) has the necessary scopes (e.g., 'repo' for GitHub). 3. Double-check your `config.yml` for correct repository names and paths.

Warnings

gotcha Decap CMS Proxy Server (`decap-server`) is designed and intended *only* for local development. By default, it runs as an unauthenticated Express server, meaning any client can send requests to it. Exposing it to the public internet without proper authentication and authorization measures is a significant security risk.
Fix: Ensure `decap-server` is only run in a secure local development environment. For more secure scenarios or production, use dedicated OAuth proxies or authenticated backends. As of `decap-cms@3.9.0`, a feature `Allow the server to be run securely` was added, but general local-only use advice remains prudent for typical setups.
breaking The minimum Node.js version required for `decap-server` is `v10.22.1`. Running with older Node.js versions may lead to unexpected errors or failures.
Fix: Upgrade your Node.js installation to a version greater than or equal to `v10.22.1`. It is recommended to use an actively supported LTS (Long Term Support) version of Node.js.
gotcha When configuring your `config.yml` for local development with `decap-server`, ensure the `local_backend.url` property correctly points to the server's address and API path (e.g., `http://localhost:8081/api/v1`). An incorrect URL will prevent the CMS from connecting to the local proxy.
Fix: Verify the `proxy_url` or `local_backend.url` in your `config.yml` matches the port and path `decap-server` is running on. The default port is 8081, and the API path is `/api/v1`.

Install

npm install decap-server npm
yarn add decap-server yarn
pnpm add decap-server pnpm

Imports

decap-server (CLI)
wrong:
```
import decapServer from 'decap-server'
```
correct:
```
npx decap-server
```
This package is primarily a command-line utility for local development. Direct programmatic import of its server instance or functions is not commonly documented or used by developers. It's intended to be run as a standalone process via `npx`.
Configuring Port
wrong:
```
npx decap-server --port 8082
```
correct:
```
PORT=8082 npx decap-server
```
The server's port is configured via the `PORT` environment variable, typically set in a `.env` file in the project root, not through a CLI argument.

Quickstart

Demonstrates setting up `config.yml` for Decap CMS to use the local proxy server, then starting `decap-server`.

{
  "backend": {
    "name": "git-gateway",
    "branch": "main",
    "local_backend": {
      "url": "http://localhost:8081/api/v1"
    }
  },
  "media_folder": "public/uploads",
  "public_folder": "/uploads",
  "collections": [
    {
      "name": "posts",
      "label": "Posts",
      "folder": "content/posts",
      "create": true,
      "fields": [
        { "label": "Title", "name": "title", "widget": "string" },
        { "label": "Publish Date", "name": "date", "widget": "datetime" },
        { "label": "Body", "name": "body", "widget": "markdown" }
      ]
    }
  ]
}
// Save the above as public/admin/config.yml

// Then, in your project root, run the server:
// npx decap-server

// If port 8081 is in use, create a .env file:
// PORT=8082
// npx decap-server

view raw JSON →