Implied - Reusable ExpressJS Components

Implied is a tool that reduces boilerplate cruft in your ExpressJS web app by providing reusable web app components.

With Implied's plugin system you can choose what components you want to use for your app, in just one line.

Quickstart

First, install implied with npm:

$ npm install --save-dev implied 

or install with yarn:

$ yarn add --dev implied

Then add config.js to your Express app's root directory. (See Configuration for more details)

module.exports = function(app){
    app.set('port', 3000);
}

Then in your app.js pass your ExpressJS app to implied and enable plugins

const implied = require('implied');
const express = require('express');

...

var app = implied(app, {
    listen: true
});

app.plugin('mongo', 'boilerplate', 'sendgrid', 'users'); // choose plugins you want in dependency order. Currently many things depend on 'mongo'.

That's it! Your app should be live at localhost:3000

Testing

Our testing enivronment uses docker for setup and configuration

To run tests, run this command docker-compose up

Configuration

Implied's configuration is done with the config.js file. To set an option for Implied, open/create your config.js file (in your project root) and add app.set($property_name, 'somevalue') to set the property_name setting to the value somevalue.

| Property | Valid Values | Default | Description | Required? | |---------------------|---------------------|--------------------------|-------------------------------------------------------------------------------------------------------------------------|-----------| | app_name | any string | project root folder name | Name of the implied application. Used to set the database name and used in transactional emails | No | | dir | any valid path | path to project root | Sets the path to the project root. Used to locate implied's config file (which is at the root) and the views directory. | No | | upload_dir | any string | app_name | Sets the name of the upload directory | No | | listen | boolean | false | If enabled makes implied listen on the port given in configuration | No | | login_url | any valid URI | /login | Sets the name of the login route | No | | forms | object | {} | Dictionary/hashmap containing jade layouts for displaying each collection in admin panel | No | | logoutSSO_Discourse | any valid URL | null | Callback URL for discourse logout SSO | No | | db_name | any valid mongo url | app_name | Mongo URI used to connect to specific database | No | | admin_email | any valid email | [email protected] | Reply email used when sending transactional emails to users | No | | error_email | any valid email | admin_email | Email address that errors are sent to when running in production mode | No | | port | integer | 3000 | Port that Implied will bind to and listen on | No | | host | valid url/domain | localhost | Host that Implied will listen on. Also used for session authentictation | No |

Mongo

The 'mongo' module wraps mongojs (a mongodb client), and sets an app variable with the database reference for use by other modules.

app.plugin('mongo');
app.get('db').collection('mycollection').find({}).toArray(function(items){
  console.log(items);
});

Users

The db.users collection contains all users creates by implied, as they sign up.

user.resetrequired can be set in a document to indicate a user must reset their password before logging in.

Boilerplate

A reasonable set of defaults for express middleware, for a typical website. It includes bodyParser, cookies, sessions. If you do need extra middleware in between the default middleware (ordinally), you won't be able to use this.

app.plugin('boilerplate');

Users

The 'users' module handles user registration, logins and password resets. Users are stored in MongoDB so this depends on the 'mongo' module.

app.plugin('mongo', 'boilerplate', 'users'); // to install

You'll need the following views with HTML forms, unless you'd rather use the rest interface.

views/pages/login.jade - contains a form with an input of name "password" and "email", at least. views/pages/signup.jade - contains a form with an input of name "password" and "email", at least. views/pages/password-reset-submit.jade - contain a form with an input of name "email".

Hooks

You can trigger something to happen when a user signs up as follows:

implied.on('signup', function(user){});

Sendgrid

Provides other modules with a wrapped sendgrid email client, app.get('mailer').

app.plugin('sendgrid');
app.get('mailer').send_mail({to:'[email protected]', subject:'Test', body:'You are reading the contents of a test email... Bored?''});

Contributing

Follow the basic design idea of being pragmatic please. New features should directly solve specific problems, and not introduce abstraction without doing so. And yes, implied is written in coffeescript. If you have a strong opinion about this... please just relax! The controversy over coffeescript is much more costly than the very minimal difference between using it and javascript :)