decap-server

library3.7.0jsnpmunverified

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.

web-framework devops workflow communication

npm install decap-server

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DECAP-SERVER

decap-server

web-frameworkjavascriptv3.7.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

decap-server (CLI)

✓ npx decap-server

✗ import decapServer from '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

✓ PORT=8082 npx decap-server

✗ npx decap-server --port 8082

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.

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

decap-server --version

Debug

Known issues

gotchaDecap 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.

affects: <3.9.0

breakingThe 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.

affects: >=3.0.0

gotchaWhen 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`.

affects: >=3.0.0

Errors

Common errors & fixes

listen EADDRINUSE: address already in use :::8081

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

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.

Upgrade

Version history

3.7.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

49 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/decaporg/decap-cms ↗

packagehttps://www.npmjs.com/package/decap-server ↗

homepagehttps://decapcms.org ↗