boxescms
ExpressJS based API centric static site CMS.
Underlying tools
Kickstart Development
-
npm init(If you haven't already) -
npm install boxescms -
npx boxes init -
npm start dev
Folder/File Structure
/.env
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/**/*.{js,json,yml}
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/
Server and node related files.
/server/api/
Only API routes. All routes are prepended with /api, appended with folder/file relative path. Routes should be declared using require('express').Router().
/server/routes/
Additional custom routes.
/web/
Web related files (html, pug, sass, scss, js, images, statics).
/web/pug
Pug files that will be compiled /public/**/*.html.
/web/{sass,scss}
SASS/SCSS files that will be compiled to /public/css/**/*.css.
/web/js
JS files that will be compiled to /public/js/**/*.js.
/web/images
Images that will be copied to /public/images.
/web/static
Statics that will be copied to /public/static.
/web/template
Pug template files for data use. See Template Data section for more details.
/public/
Web files will be compiled here, and served as root static by Node server.
/storage/
Contents should be ignored. Storage folder for various runtime data usage.
/conf/
External configuration files.
/webpack.merge.js
Optional Webpack configuration. This configuration will be merged into the default configuration.
Builders
JS
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:
- When compiling
/web/pug/[**/*].pugfile, 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
head
title=pagetitle
- /data/page.yml
pagetitle: Hello World
- /public/page.html
<head><title>Hello World</title></head>
- If a data file in
/data/**/*.{js,json,yml}has a key.template, the.templatevalue will use/web/templateas 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
head
title=pagetitle
- /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
resolve(data)
})
- /public/dashboard.html
<head><title>Dashboard</title></head>
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.