Generator-guts NPM

Guts Generator

A Yeoman generator for scaffolding ExpressJS routers and MongoDb data services

Overview

Guts is designed to accelerate back-end development by providing boilerplate functionality common to modern web applications. It should give you a great starting point to experiment with JSON Web Tokens, REST APIs, and MongoDb queries using Mongoose.

Setup

Before starting you will need an existing Express.js project and a local running instance of MongoDb.

Installation

npm install -g generator-guts

Usage

yo guts

The default menu will give you an option to create a REST API, a MongoDb data service or a new router. Make sure you are in your project's root directory before running a generator.

API

yo guts:api

Dependencies

The API generator creates a new router in your project at ./routes/api/index.js. This router has a dependency on the jsonwebtoken and body-parser packages which you may allow the generator to install for you.

The body-parser middleware reads POST data from incoming HTTP requests. You must configure it properly for the API router to work. This is done in your entry point file (usually called app.js, index.js, main.js or server.js). See docs for clarification.

Setup

After the router has been generated, you must import it in your entry point file:

var apiRouter = require('./routes/api/index');

// body-parser configuration goes here
// before the api router

app.use('/api', apiRouter);

Now start the server and visit http://localhost:3000/api.

Authentication

The API router has 1 protected endpoint. To view this resource you must first retrieve a token by making a POST to the /api/authenticate route. This can be done using the Postman Chrome App, or from your terminal with cURL:

curl -X POST 'http://localhost:3000/api/authenticate'

Visit http://localhost:3000/api/protected?token=<token>.

Note:

The API router is a simplified demonstration of JSON Web Tokens and is meant to serve as a prototype. For an extended discussion see further reading.

Data Service

yo guts:data

The Data Service generator allows you to create data models and expose them to your project using a service module. This service module is placed into your project's node_modules folder when you run the generator. You may also generate models using the guts:model generator which has a --path option (see Options).

Dependencies

The Data Service entry point file located at node_modules/<data-service-name>/index.js uses mongoose to connect the service to your mongodb instance, then exposes each data model. Whenever you generate a new data model remember to reference it in this file.

When you create a User data model the resulting file, User.js has a static User.create method that uses bcrypt to hash the password (see node_modules/<data-service-name>/User.js).

Sidenote: If you want to verify a user password use the bcrypt.compare method:

    bcrypt.compare(plainTextPassword,
                   user.password,
                   function(err, isvalid) {
                        if(isValid) ... // verified
                    })

Usage

After you have generated your data service it may be referenced from anywhere in your project. Its data models are public properties:

var db = require("<data-service-name>");
var User = db.User;
User.create({name:'Clark', password:'Kent'},
             function(err, user){
                //...
             });

Router

yo guts:router

You may create a Custom, Upload or CRUD router using the Router generator. Remember that after you create a router it must be imported in your project's entry point file with require("<router-location>") then app.use() (see API, setup).

Router Type	Location
CRUD	`./routes/<model-name>/index.js`
Custom	`./routes/<router-name>/index.js`
Upload	`./routes/upload/index.js`

CRUD Router

You must have an existing Data Service with at least one data model before generating a CRUD router. This router will expose Create, Read, Update and Delete operations for your data model. This router may also be generated using guts:crud "<data-service-name>" "<model-name>". Like the API generator, this generator has a dependency on body-parser.

Router Endpoints

Method	url
POST	/
GET	/
PUT	/:id
DELETE	/:id

The POST endpoint requires a JSON body parameter with a property named after your data model. Any fields on the property not defined in your model's schema will not be saved to the database, so make sure that your data model's mongoose schema is defined. For a more detailed discussion see Mongoose Schemas.

The PUT endpoint requires a url parameter for the id and a JSON body parameter that has an update property for the new field values. For more details check out the docs.

Custom Router

The Custom router has a default route that returns a generic message.

Upload Router

The Upload router has a default route that uploads files to your machine's /tmp folder. This router has a dependency on express-fileupload. The Router Generator will prompt you for installation of this package if you select Upload as the Generator Type.

express-fileupload must be configured in your project's entry point file (see docs).

After setting up your router, run your application and use Postman or a similar tool to POST form data and files to the /upload route. When uploading be sure to provide a key name for the file, otherwise the file will not be moved to the /tmp folder.