Node-Koa-Mongo-Swig boilerplate app; readily deployable to Heroku for instant lulz.

Make sure you have node 0.11.x installed, as Koa requires generators.

• You can install node 0.10.33 (or the latest stable version of node) here
• Then install n, a nifty node management tool, with npm install -g n in your terminal
• Once n is installed, then run n 0.11.14
• Install mongoDB here

Afterwards, run the following commands:

$ git clone [email protected]:lambtron/node-koa-mongo-swig-seed.git
$ cd node-koa-mongo-swig-seed
$ mongod
$ make

You should see:

listening on port 3000

Then, point your browser to localhost:3000.

Make sure you have a Heroku account and you have Heroku's CLI installed. Afterwards, run the following commands.

$ heroku create
Creating polar-escarpment-5726... done, stack is cedar-14
https://polar-escarpment-5726.herokuapp.com/ | [email protected]:polar-escarpment-5726.git
Git remote heroku added
$ git push heroku master

Then, point your browser to https://polar-escarpment-5726.herokuapp.com/.

.
+-- bin
|   +-- server
+-- lib
|   +-- models.js
|   +-- render.js
|   +-- twitter.js
+-- server
|   +-- routes.js
|   +-- tweet.js
+-- views
|   +-- index.html
|   +-- layout.html
+-- .gitignore
+-- LICENSE
+-- Makefile
+-- package.json
+-- Procfile
+-- README.md

This is the basic structure of the Node-Koa app. Logic is separated out between bin (configuration of the server), lib (setting up libraries for any area of the app to use), server (server-side logic), views (front-end templating), and the Makefile. We will dive deeper into the aforementioend directories, but first a high level overview of the top-level files.

This tells git which files to ignore. For node apps, the most common are node_modules (the app's dependencies), .DS_Store (tells the computer how to format the directory's icons—completely useless in coding), and logs (error or debug logs). Other people working on the repo derive no value in seeing these settings, which is why it is best that git ignores them.

More about .gitignore.

A software license that describes how your code can be used by others.

Once upon a time, software was tedious to compile and run, especially when you had to include several source files and execute a series of commands each time. The emergence of Makefiles simplifies this process dramatically.

The Makefile defines a series of instructions that will build and derive the target program, which can be executed within a set of defined commands.

In our Makefile, we define make clean (remove non-checked-in depedencies), make debug (run in debug mode), make run (run the server), and make server (run the server with nodemon for development purposes). The default setting, which is called when you just call make, will call make run.

More about Makefiles.

This file holds all the metadata related to your app or project. This file is used to give information to npm that allows it to identify the project and its dependencies. This also contains other metadata around the app's description, version, license, and configuration data.

All of the dependencies are located in the dependencies property. When you call npm install, those are the dependencies and their versions that are installed locally under node_modules.

More information about package.json.

This is a Heroku specific file that tells Heroku how to run the app. Heroku has various workers, one of them being web, which we have to provide the command to initiate the server. In our case, the server can be started with the make command, which is why our Procfile is just web: make. In other cases, it can be web: node server.js or web: rails s, etc.

More information about Procfiles.

This arguably the most important file, as it is the first piece of information a new programmer interacts with to understand your software. For guides to write great readmes, check out the below:

• How to write a great README
• How to write a Readme worth reading

The make run, make server, and make debug commands all call --harmony bin/server. The first line of bin/server has #!/usr/bin/env node, which tells the computer how to execute the rest of the file.

The server file is for setting up the server. Here you'll see the PORT being defined, the various middleware that the server will use, configuring the routes, and finally initializing the server.

The configuration of the routes is just mapping paths to functions; i.e. '/' to routes.index, which is defined in the server/routes.js file.

This folder contains all files that have "helper" code that any other area of the code base can use, which normally is:

• to connect to the database
• to connect to templating engine
• to connect to any wrapper libraries

In models.js, it is important to replace the address to the mongo database, as well as recognize that process.env.MONGOHQ_URL is the environmental variable that Heroku sets when you use mongoHQ as an add on.

Also, the YOUR_MODEL name should be the object that you are saving in the database, while the file name should be plural of said object. For example, if you are saving users in your database, the model name should be user and the filename be users.js.

In render.js, we are telling swig, a node.js templating engine, where to find the HTML files that will be used as templates, and then exposing swig.

In twitter.js, we are initializing the library, setting the credentials, and then exposing a 'thunkified' instance. Note that twitter.js is just an example; any wrapper library can be added here, but the main intent is just to initialize (with credentials) and expose it so that any other file that requires the file can use it immediately.

This folder contains all files that uphold the back end logic. Whereas the bin folder focused on configuring the server and the lib folder just made available libraries for other files to use, the server folder has the main business logic.

In routes.js, we are setting the routes in each function (i.e. index() will render index.html). Remember, these functions are exposed via the Routes object in the bin/server file, which maps each Routes function to a path.

We also require some of the files in the ./lib folder. Now these objects and its functions can be used right here, such as the render() function.

In tweet.js, we are simply adding another level of abstraction between the routes.js file and the various functions associated with the twitter.js library.

This folder contains all of the front-end swig templates that will be populated by data sent from routes.js (with this command).

Refer to the swig documentation for more information.

WWWWWW||WWWWWW
 W W W||W W W
      ||
    ( OO )__________
     /  |           \
    /o o|    MIT     \
    \___/||_||__||_|| *
         || ||  || ||
        _||_|| _||_||
       (__|__|(__|__|

Copyright (c) 2014

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.