Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


0.11.0 • Public • Published


ExpressJS based API centric static site CMS.

Underlying tools

Kickstart Development

  1. npm init (If you haven't already)

  2. npm install boxescms

  3. npx boxes init

  4. npm start dev

Folder/File Structure


Env variables. Copy from .env.example.

/app.js (optional)

Optional app.js to extend the Express app instantiated from BoxesCMS. Must export a function or preinit/postinit functions that receives the app as first argument.


Data layer as Pug locals for static HTML generation. For js type, it must export an object. See Template Data section for more details.


Server and node related files.


Only API routes. All routes are prepended with /api, appended with folder/file relative path. Routes should be declared using require('express').Router().


Additional custom routes.


Web related files (html, pug, sass, scss, js, images, statics).


Pug files that will be compiled /public/**/*.html.


SASS/SCSS files that will be compiled to /public/css/**/*.css.


JS files that will be compiled to /public/js/**/*.js.


Images that will be copied to /public/images.


Statics that will be copied to /public/static.


Pug template files for data use. See Template Data section for more details.


Web files will be compiled here, and served as root static by Node server.


Contents should be ignored. Storage folder for various runtime data usage.


External configuration files.


Optional Webpack configuration. This configuration will be merged into the default configuration.



There is 2 special env var that you can use in your JS files:

  • process.env.VERSION
  • process.env.BUILD_HASH

process.env.VERSION is taken from your project's package.json.version.

process.env.BUILD_HASH is a randomly generated per build 64 length hex char.

Template Data

The data files in /data/**/*.{js,json,yml} is used in 2 ways:

  1. When compiling /web/pug/[**/*].pug file, if there is a matching /data/[**/*].{js,json,yml} file, it will use the data file as the locals for Pug compilation. The pug files will be compiled to /public/[**/*].html.
  • /web/pug/page.pug
  • /data/page.yml
pagetitle: Hello World
  • /public/page.html
<head><title>Hello World</title></head>
  1. If a data file in /data/**/*.{js,json,yml} has a key .template, the .template value will use /web/template as root to search for the pug file to compile, e.g.: /web/template/['.template'].pug}. The output file for /data/[**/*].{js,json,yml} is /public/[**/*].html
  • /data/page.json
  ".template": "base.pug",
  "pagetitle": "Hello World"
  • /web/template/base.pug
  • /public/page.html
<head><title>Hello World</title></head>

Dotfiles Template Data (JS)

Apart from a general template data, you can create dotfiles to create multiple pages under a single template. Currently only supports .js file, in /data/**/.*.js

The data file must contain .template key to define what template to use. Subsequent keys will be the page to create, and the value is an object of the locals to use for that page.

The file should export a Promise instance, in which allows you to perform async operations to populate the final object to resolve.

  • /data/.pages.js
const data = {
  '.template': 'index.pug',
  '/dashboard': {
    title: 'Dashboard'

module.exports = new Promise((resolve, reject) => {
  // async operations if needed

  • /public/dashboard.html

Server Debug Mode

The node inspector can be enabled by passing --inspect [port=9229] to boxes start command. You can either use chrome://inspect on Chrome browser to use the default .vscode/launch.json from init to attach debugger.




npm i boxescms

Downloadsweekly downloads









last publish


  • avatar
Report a vulnerability