{"id":15310,"library":"decap-server","title":"Decap CMS Proxy Server","description":"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.","status":"active","version":"3.7.0","language":"javascript","source_language":"en","source_url":"https://github.com/decaporg/decap-cms/tree/main/packages/decap-server","tags":["javascript","decap-cms","backend"],"install":[{"cmd":"npm install decap-server","lang":"bash","label":"npm"},{"cmd":"yarn add decap-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add decap-server","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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`.","wrong":"import decapServer from 'decap-server'","symbol":"decap-server (CLI)","correct":"npx decap-server"},{"note":"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.","wrong":"npx decap-server --port 8082","symbol":"Configuring Port","correct":"PORT=8082 npx decap-server"}],"quickstart":{"code":"{\n  \"backend\": {\n    \"name\": \"git-gateway\",\n    \"branch\": \"main\",\n    \"local_backend\": {\n      \"url\": \"http://localhost:8081/api/v1\"\n    }\n  },\n  \"media_folder\": \"public/uploads\",\n  \"public_folder\": \"/uploads\",\n  \"collections\": [\n    {\n      \"name\": \"posts\",\n      \"label\": \"Posts\",\n      \"folder\": \"content/posts\",\n      \"create\": true,\n      \"fields\": [\n        { \"label\": \"Title\", \"name\": \"title\", \"widget\": \"string\" },\n        { \"label\": \"Publish Date\", \"name\": \"date\", \"widget\": \"datetime\" },\n        { \"label\": \"Body\", \"name\": \"body\", \"widget\": \"markdown\" }\n      ]\n    }\n  ]\n}\n// Save the above as public/admin/config.yml\n\n// Then, in your project root, run the server:\n// npx decap-server\n\n// If port 8081 is in use, create a .env file:\n// PORT=8082\n// npx decap-server\n","lang":"yaml","description":"Demonstrates setting up `config.yml` for Decap CMS to use the local proxy server, then starting `decap-server`."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"<3.9.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`.","cause":"The default port 8081 is already being used by another application on your system.","error":"listen EADDRINUSE: address already in use :::8081"},{"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.","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`.","error":"Failed to load entry: API Error"}],"ecosystem":"npm"}