convention-based platform for custom Express + Handlebars + Mongoose + Passport + Bootstrap sites


TR;DL: Platform for building custom Express + Handlebars + Mongoose + Passport + Bootstrap sites quickly.

A server-side node module that utilizes popular NPM modules and a set of simple file layout conventions to make putting together an efficient, new, custom site easy and efficient.

PlatformJS qualifies as "opinionated" software. The primary purpose of the platform is to allow tie together existing, high-quality libraries into a new site very quickly; it is quite difficult to serve this purpose effectively without making presumptions about which libraries to use.

The basic server is with no content or custom configuration isn't very interesting, however to get a minimal server going:

In a file server.js:

var platformjs = require("platformjs-core");    
var platform = new platformjs.Platform;

Then start the server with:

$ node server.js

If you visit http://localhost:8080, you should then get a message Cannot GET /. This is correct behavior as the site has no content.

All content, customization, and plug-ins are read in from the subdirectories of a special extensions subdirectory. Within that directory, there are conventions for content -- such as the public directory being used to directly server static content:

  1. Create a subdirectory extensions/mysite/public
  2. Add a new file index.html with some HTML content
  3. Visit http://localhost:8080
  4. Your new page should be displayed
  1. Create a public directory within the extension
  2. Files will be served as-is

Note: if a public/favicon.ico file is located, it will automatically be special-cased to use the express favicon middleware for efficiency.

  • TBD: Less files, minified JS, Handlebars templates,
  • TBD: Browserify bundles

The protected/ sub-directory can be used similiarly to the public/ sub-directory, except for generated files. For example, a file named protected/user/dashboard.hb.html represents a Handlebars template that is automatically routed as a rendered template to /user/dashboard.


Templates currently use a version of Handlebars with a few simple extensions.

Templates should end with an .hb.html extensions.

The built in extensions to the Handlebars include:

{{#markdown}}{{/markdown}} can be used to include markdown within the page.

{{#context}}{{/context}} text within this block is treated as JSON which is merged into the template context. This is useful to "locally" define variables in the template without modifying the code. This can be useful for generating tables of data or other repeated elements.

All files in the partials directory with a .hb.html are considered Handlebars partials.

For example, if there is a file partials/base-stylesheets.hb.html, it will can be inserted into another template via:

   {{> base-stylesheets }}

Note: The current implementation does not support nested sub-directories within this sub-directory.

In order to control the precedent of settings that overlap between extensions, each extension is given a priority.