Decap CMS Quickstart

Quickly add Decap CMS to a Webpack project

Important

This guide assumes you're familiar, at least conceptually. with Webpack. If not, no problem! Webpack is a module bundler. In a nutshell, it handles a project's setup and housekeeping, and lets you get straight to writing functional code. The Webpack Template will help!

This guide speedruns steps 1 (installation) and 2 (backend config) of Decap's Basic Steps guide.

Instructions

There's five steps:

1. Copy the CMS files into your project
2. Install the necessary npm packages
3. Update your webpack.config.js
4. Update your package.json
5. Launch and test!

And, optionally,

6. Customize your icon and CMS appearance

1) Copy CMS files

In your project's src folder, import the CMS folder and all its files found in this repo's src.

The cms.zip file also contains that directory, for quick download.

Note

This guide uses "cms" as the name for the CMS subfolder, but "admin" is also common naming convention. If you'd prefer to use "admin" or something else, simply change the directory name to match.

If you're using the Decap Webpack config template in Step 3A, you'll also need to change CMS_FOLDER to match - but worry about that in a couple minutes, when you're there ;)

2) Install npm packages

Install the following npm packages as dev dependencies by running the following terminal commands:

1. CopyWebpackPlugin - Package, repo, docs
   Copies source files to output folder, eg from ./src/cms to ./dist

   npm i copy-webpack-plugin --save-dev
   

2. npm-run-all2 - Package, repo
   Allows executing multiple npm commands at once (see Step 4)

   npm i npm-run-all2 --save-dev
   

Note

If you're starting really fresh and haven't already initialized npm in this project, execute npm init -y

3) Update your webpack.config.js

The template webpack.config.cjs file is already prepared for use. If you're using that template (fastest method), follow Step 3A.

If your webpack.config is based off of the Webpack Template (or webpack.config.cjs Gist), follow Step 3B.

If you've written your own webpack.config file or gotten it from elsewhere, follow Step 3C.

3a) Using this repo's webpack.config.cjs template

These steps are detailed in the template file itself, but for the sake of having it all together:

1. Ensure the webpack.config.cjs file is in your project's root directory

2. Update SITE_TITLE, line 151, to your desired title

   • If you've changed the "cms" folder name to something else (such as "admin"), update CMS_FOLDER to match.
   • If needed, also change the other config properties like SRC_FOLDER or INDEX_FILE.

3. If you haven't already, install all other relevant npm packages with these two commands (in addition to the ones installed in Step 2):

   npm i webpack webpack-cli webpack-dev-server webpack-remove-empty-scripts css-loader html-webpack-plugin mini-css-extract-plugin postcss-loader --save-dev
   

   npm i typescript jquery
   

3b) Using the WebpackTemplate repo config

Update the webpack.config.cjs file like so:

1. At the end of #region Config, line 149, add:

   /** Name of the folder, in both source and dist output, for the CMS. */
   const CMS_FOLDER = 'cms';
   

2. At the end of the plugin declarations, line 169 (or line 172 after the previous step), add:

   /** A Webpack plugin to copy existing individual files or entire directories into the build directory.
    * @see https://webpack.js.org/plugins/copy-webpack-plugin/ */
   const CopyWebpackPlugin = require("copy-webpack-plugin");
   
   /** Full path of the CMS subfolder. Ignored in module rules, used by {@linkcode CopyWebpackPlugin. @type {string} */
   const CMS_FULL_PATH = path.resolve(__dirname, `${SRC_FOLDER}/${CMS_FOLDER}`);
   

3. In the plugins array of your module.exports return function, line 204 (or line 213 after previous steps), append:

   new CopyWebpackPlugin({
       patterns: [
           {
               from: CMS_FULL_PATH,
               to: CMS_FOLDER,
               noErrorOnMissing: true,
           },
       ],
   }),
   

4. Replace devServer, line 225 (or line 243 after the previous steps), with:

   devServer: {
       static: [
           OUTPUT_FOLDER,
           { directory: CMS_FULL_PATH, publicPath: `"/${CMS_FOLDER}` },
       ],
       watchFiles: [`${SRC_FOLDER}/${CMS_FOLDER}/**/*`],
   },
   

5. In the CSS loading module, exclude the CMS filepath by adding the following exclusion between the test and use properties, line 247 (or line 269 after the previous steps):

   exclude: CMS_FULL_PATH,
   

3c) Modifying webpack.config directly

This assumes you're using a typical webpack.config.js file, such as the barebones example in this repo.

1. Import the copy-webpack-plugin at the top of your config file, alongside where path is imported.

   const CopyWebpackPlugin = require("copy-webpack-plugin");
   

2. In the plugins array of your module.exports return function, create a new CopyWebpackPlugin with the following parameters:

   new CopyWebpackPlugin({
       patterns: [
           {
               from: path.resolve(__dirname, `src/cms`, // your working CMS folder, typically in /src
               to: 'cms', // desired name of the CMS subdirectory in your dist/build folder
               noErrorOnMissing: true,
           },
       ],
   }),
   

   The noErrorOnMissing pattern is optional.

4) Update package.json

This is useful if you want to simply execute npm start and have your development CMS enabled, instead of having to execute npm start to launch Webpack, and then execute npx decap-server to launch your local Decap server.

Note

The run-p command runs multiple commands in parallel. This is why we installed npm-run-all2 in Step 2.

In your package.json file's scripts, add the following.

"start": "run-p start:byconfig server",
"start:byconfig": "webpack serve --open",
"start:dev": "webpack serve --mode=development --open && npx http-server dist",
"start:prod": "webpack serve --mode=production --open",
"server": "npx decap-server",

Whether or not you're using the Webpack Template, this will replace the "start" command. If you are using the template, this will also replace the "start:dev" and "start:prod" commands. In either case, the "start:byconfig" and "server" commands are new.

5) Launch and test your CMS

Now when you test your site via npm start in VS Code, it should also start your local Decap server. When your browser opens to localhost:8080 (or whatever your local test URL may be), add /cms to it and test out your new CMS!

Next up, time to configure the CMS to your specific project. Have fun 💖

6) Optional: Customization, config.yml, and index.html

Icon

• Change icon.png to whatever you like. It's synced to be both the site icon and CMS header icon. I can't imagine why you'd want anything besides a duck, though. Ducks are great.

config.yml

You'll spend a lot of time in config.yml as you set up your CMS. Below are a couple quick notes on modifying it for now.

• Update the production backend URLs. Eventually you'll want to use the production backend when your project goes live. By default, those URLs point to this quickstart repo. You should point them towards your own site. All URL lines are marked with a # <----- REPLACE URL comment.
• If you've changed the icon name, update logo: src: MyNewIcon.png. If you want it to appear on the start page but not in the CMS itself, set show_in_header to false. If you want it gone altogether, delete the entire logo block.
• The media_folder and public_folder are where your content lives. Customize them as needed, per Decap's Media/Public Folder documentation.
• Collections are where you'll begin to set up your CMS structure. Customize it as needed, per Decap's Collections documentation.

index.html

Updating index.html isn't at all necessary, but offers some customization.

• Change the <title> element to whatever you want your CMS to be called, if you find "Decap CMS" uninspiring
• If you've changed the icon, change the ''s href` value to your new icon. This way you can specify a different icon between the webpage and the CMS header.
• By default, Decap is loaded from UNPKG, and it loads v3.0.0
  • If you want to load from its jsDelivr mirror, comment the unpkg script line, and uncomment the jsDelivr script line.
  • If you want to load another version, change the ^3.0.0 to whichever version you'd like, or remove it altogether for the latest version. Eg, at the time of writing this, directly loading unpkg.com/decap-cms (or cdn.jsdelivr.net/npm/decap-cms) loads v3.10.0
• Comment out the decapServerWarning script if you want to skip it. It simply waits for the CMS to connect, and if connection fails, reminds you to check config.yml and ensures that you launched the server correctly from terminal. Upon successful connection, it automatically disables itself.