README.md

Server Extensions

Express.js

Entry Point

Bootstrapping is happening in ./server/index.coffee. You usually don't need to touch this file. If you want to extend the functionality of the Server you should use the ./server/initialize directory (see below).

Configuration

All configuration goes in ./server/config.coffee and is passed along to initilization and routes (see examples below).

The default port of the Server is 7799. The default static directory is ./public - generated by gulp build (you want to run gulp watch to pick up file changes while developing).

Initilization

The Entry Point will load and initialize all files that are in ./server/initialize. For example ./server/initialize/app.coffee will initialize the JSON Body Parser and the static directory:

module.exports = (config, helpers, io, models) ->
  @use express.static(config.server.publicDir)
  @use bodyParser.json()

The context (@/this) is the express() app that is initialized in the Entry Point.

Routes

Pretty much the same as the Initilization files, the Entry Point will load all files in ./server/routes. Split the files depending on your resources and define all related routes in them. For example ./server/routes/app.coffee:

module.exports = (config, helpers, io, models) ->
  @get '/hello/:name', (req, res) ->
    res.json { str: helpers.app.sayHello(req.params.name) }

  @post '/whatever, (req, res) ->

Helpers

Helpers are commonly used functions that can be shared between initilization, routes and models. They are passed to the exported function as seen in the examples above.

All helpers will be loaded from the directory ./server/helpers.

The name of the file is important, as it's used to populate the helpers object. For example ./server/helpers/app.coffee:

module.exports =
  sayHello: (toName) ->
    "Hello #{toName}!"

Will be available as helpers.app.sayHello(). A file ./server/helpers/string.coffee would be available as helpers.string.*.

Helpers should only work with raw data and should not interact with the Express app or models in any way.

Start Server for Development

When in development environment, use npm start. This will start a Forever process that still logs to STDOUT. It will watch the ./server directory for any file changes and restarts the server.

You'd still need to reload the browser manually. Unfortunately I haven't found a reliable solution for this yet.

Lodash

Lodash is already installed for convinience. Just do _ = require('lodash') anywhere and hack away.

Socket.io

A Socket.io Server is automatically initialized on the Entry Point and is served at the same port as the HTTP Server. The io object is passed to the initilization and the routes, see the examples above.

MongoDB with Mongoose (Optional)

You can define Mongoose models in ./server/models. For example ./server/models/count.coffee:

module.exports = (helpers) ->
  @model 'Count',
    visits: Number

The context (@/this) is the mongoose object defined in the Entry Point. Just make sure that the mongoose.model definition is returned.

Models are initialized in the models object and passed to initilization as well as routes. Just as the helpers it is important how you name the files, as it is the key the model is initialized with. The example above would be located at models.count. A usage example would be:

module.exports = (config, helpers, models) ->
  @get '/count', (req, res) ->
    models.count.findOne {}, (err, count) ->
      unless count
        count = new models.count({ visits: 0 })

      count.visits += 1
      count.save()

      res.json count.toJSON()

The Server Entry Point only tries to connect to the database defined in the config file if there are any model files. So you might use the Server without any database connection by leaving the ./server/models directory empty or remove it altogether.

yo grail:create - Generate a Server Component

With the yo grail:create you can quickly create a Server Component consisting of Initialize, Helper, Route and/or Model. All are optional.