ExpressJS is an awesome tool to build small web application. But once you start using it, you discover that writing the configuration and the routes often leads to ugly code. To solve that, Americano acts as a wrapper around Express and make it more opinionated about how to write routes and configuration. See in the following how it make things cleaner.

Americano is:

• a tool to quickstart small web applications or web modules.
• oriented to build single page-app and REST API.

Americano is not:

• a full-featured framework for making big web applications.

NB: Americano inherits all the ExpressJS features

There is a binary provided with Americano to start quickly your project:

npm install americano -g

americano blog

create: blog
create: blog/package.json
create: blog/server.js
create: blog/README.md
create: blog/client/public
create: blog/server/models
create: blog/server/controllers
create: blog/server/controllers/routes.js
create: blog/server/controllers/index.js
create: blog/server/config.js

install dependencies:
$ cd blog && npm install

Run your application:
$ npm start

americano --coffee blog

To write an Americano application you need to add it as a dependency of your package.json file.

npm install americano --save

Then you must to create your main file:

// ./server.js
var americano = require('americano');

var port = process.env.PORT || 3000;
americano.start({name: 'yourapp', port: port}, function(err, app, server) {
  // Do something when everything is properly started.
});

Americano requires a config file located at the root of your project, let's add it:

// ./server/config.js
var americano = require('americano');

module.exports = {
  common: { 
    use: [
      americano.bodyParser(),
      americano.methodOverride(),
      americano.static(__dirname + '/../client/public', {
        maxAge: 86400000
      })
    ]
    useAfter: [
      americano.errorHandler({
        dumpExceptions: true,
        showStack: true
      })
    ]
  },
  development: {
    use: [
      americano.logger('dev')
    ],
    set: {
      debug: 'on'
    }
  },
  production: [
    americano.logger('short')
  ]
};

Once configuration is done, Americano will ask for your routes to be described in a single file following this syntax:

// ./server/controllers/routes.coffee
var posts = require('./posts');
var comments = require('./comments');

module.exports = {
  'posts': {
    get: posts.all,
    post: posts.create
  },
  'posts/:id': {
    get: posts.show,
    put: posts.modify,
    del: [posts.verifyToken, posts.destroy]
  },
  'posts/:id/comments': {
    get: comments.fromPost
  },
  'comments': {
    get: comments.all
  }
};

Your controllers can be written as usual, they are ExpressJS controlllers.

You're done! Just run node server.js and you have your configured Express web server up and running!

By the way this is how your single-page app looks like with Americano:

your-blog/
    server.js
    server/
        config.js
        controllers/
            routes.js
            posts.js
            comments.js
        models/
            post.js
            comment.js
    client/
        ... front-end stuff ...

Americano allows to use plugins that shares its philosophy of making cleaner and more straightforward things.

Actually there is only one plugin, feel free to add yours:

• cozy-db: a plugin to make Cozy application faster.

Here is what I would like to do next:

• make a plugin for socket-io
• make a plugin for mongoose
• make a plugin for sqlite
• make a plugin for cozy-realtime-adapter

I didn't start any development yet, so you're welcome to participate!