roosevelt

roosevelt.js

Roosevelt is a new web framework for Node.js which uses Teddy for HTML templating and LESS for CSS preprocessing.

Built on Express, Roosevelt is designed to abstract all the crusty boilerplate necessary to build a typical Express app, sets sane defaults with mechanisms for override, and provides a uniform MVC structure for your app.

Why use Roosevelt?

Roosevelt is easy to use and has a low learning curve, unlike many other popular Node.js-based web frameworks.

Reasons for this include:

• Minimal boilerplate to get started. All the magic of Express is preconfigured for you.
• Default directory structure is simple, but easily configured.
• Concise MVC architecture.
• Teddy HTML templates are much easier to read and maintain than popular alternatives.
• Built-in support for load balancing using the Node.js cluster module.

Make a Roosevelt app

Install the command line tool globally (may require sudo):

npm install -g roosevelt

Use the command line tool to create a sample app:

roosevelt create myapp

Change into your new app's directory and then install dependencies:

cd myapp
npm install

Run your app:

node app.js

Other ways to run Roosevelt apps

Run your app on two CPUs:

node app.js -cores 2

Run your app on all your CPUs:

node app.js -cores max

While developing your app, a better way to run the app is to use the developer mode.

When your app is running in developer mode, it will automatically restart whenever you modify any JS, JSON, LESS, or HTML files.

To run your app in developer mode, first npm install -g nodemon (may require sudo), and then simply execute this command:

npm start

Default directory structure

• app.js: main app file
• mvc: folder for models, views, and controllers
  • controllers: folder for controller files
  • models: folder for model files
  • views: folder for view files
• statics: folder for CSS, images, JS files, LESS files, and other statics
  • css: folder for CSS files
  • images: folder for image files
  • js: folder for JS files
  • less: folder for LESS files

Minimal boilerplate

All that's in app.js is this:

require('roosevelt')({
/*
  param name:               default value

  name:                     'Roosevelt Express',
  port:                     43711,
  modelsPath:               'mvc/models',
  viewsPath:                'mvc/views',
  controllersPath:          'mvc/controllers',
  notFoundPage:             '404.js',
  staticsRoot:              'statics',
  cssPath:                  'statics/css',
  lessPath:                 'statics/less',
  prefixStaticsWithVersion: false, // changes static urls like /css/file.css to /{versionNumber}/css/file.css
  versionNumberLessVar:     '', // populate statics/less/version.less with a LESS variable of this name
  formidableSettings:       {}, // settings to pass to formidable: https://github.com/felixge/node-formidable#api

  events:                   sample function

  onServerStart:            function(app) {
                              // code which executes when the server starts
                            },
  onReqStart:               function(req, res, next) {
                              // code which executes at the beginning of each request
                              // must call next() when your code finishes
                            },
  onReqBeforeRoute:         function(req, res, next) {
                              // code which executes just before the controller is executed
                              // must call next() when your code finishes
                            },
  onReqAfterRoute:          function(req, res) {
                              // code which executes after the request finishes
                            }
*/
});

Roosevelt is designed to have a minimal amount of boilerplate so you can focus on just writing your app. All parameters are optional.

Configure your app

Roosevelt will determine your app's name by examining "name" in package.json. If none is provided, it will use Roosevelt Express instead.

Inside app.js, you can pass any of the below optional parameters to Roosevelt. Each can also be defined in package.json under "rooseveltConfig".

Option	Description	Default
port	The port your app will run on.	Either process.env.NODE_PORT or if that's undefined, then 43711
modelsPath	Path on filesystem to where your model files are located.	mvc/models
viewsPath	Path on filesystem to where your view files are located.	mvc/views
controllersPath	Path on filesystem to where your controller files are located.	mvc/controllers
notFoundPage	Relative path on filesystem to where your "404 Not Found" controller is located. If you do not supply one, Roosevelt will use its default 404 controller instead.	404.js
internalServerErrorPage	Relative path on filesystem to where your "500 Internal Server Error" controller is located. If you do not supply one, Roosevelt will use its default 500 controller instead.	500.js
serviceUnavailablePage	Relative path on filesystem to where your "503 Service Unavailable" controller is located. If you do not supply one, Roosevelt will use its default 503 controller instead.	503.js
staticsRoot	Path on filesystem to where your static assets are located. All files and folders specified in this path will be exposed as statics.	statics
cssPath	Path on filesystem to where your CSS files are located.	statics/css
lessPath	Path on filesystem to where your LESS files are located.	statics/less
prefixStaticsWithVersion	If set to true, Roosevelt will prepend your app's version number from package.json to your statics URLs. Versioning your statics is useful for resetting your users' browser cache when you release a new version.	false
versionNumberLessVar	When this option is activated, Roosevelt will write a file named version.less to your less directory containing a variable with your desired name populated with your app's version number derived from package.json. This option is disabled by default. Activate it by supplying a desired variable name to the parameter. This feature is useful in conjunction with prefixStaticsWithVersion, as it allows you to construct URLs in your LESS files such as url('/@{staticsVersion}/images/i.png'), allowing you to version all of your statics at once simply by changing your app's version number in package.json.	undefined
formidableSettings	Settings to pass along to formidable using formidable's API.	undefined
shutdownTimeout	Maximum amount of time given to Roosevelt to gracefully shut itself down when sent the kill signal.	30000 (30 seconds)

Roosevelt also provides a series of events you can attach code to by passing a function to the desired event as a parameter.

Event	Description	Arguments passed
onServerStart	Fired when the server starts.	app: the Express app created by Roosevelt.
onReqStart	Fired at the beginning of each new request.	req: the request object created by Express. res: the response object created by Express. next: callback to continue with the request. Must be called to continue the request.
onReqBeforeRoute	Fired just before executing the controller.	req: the request object created by Express. res: the response object created by Express. next: callback to continue with the request. Must be called to continue the request.
onReqAfterRoute	Fired after the request ends.	req: the request object created by Express. res: the response object created by Express.

Defining routes (URL endpoints)

A route is the term Express uses for URL endpoints, such as http://yoursite/blog or http://yoursite/about. To make a new route, just make a new file in the controllers directory.

Making controller files

Controller files are just standard Express routes. For example:

module.exports = function(app) { // app is the Express app created by Roosevelt

  // standard Express route
  app.get('/about', function(req, res) {
  
    // use Roosevelt to load a data model
    var model = app.get('model')('about');
    
    // render a Teddy template and pass it the model
    res.render('about', model);
  });
};

Making model files

Since the above example requires a model file named about, you will need to make that too. To do that, place a file named about.js in mvc/models.

Here's a simple example about.js data model:

module.exports = {some: 'data'};

Making view files

Views are Teddy templates. See the Teddy documentation for information about how to author Teddy templates.

Using LESS with Roosevelt

Using LESS with Roosevelt is optional.

Roosevelt will automatically compile any (.less) files in your LESS folder down to minified CSS (.css) files of the same name in your CSS folder. Note: This will overwrite any preexisting CSS files of the same name, so be careful.

The CSS minifier used by LESS is YUI Compressor.

Express variables exposed by Roosevelt

Roosevelt supplies several variables to Express that you may find handy. Access them using app.get('variableName').

Express variable	Description
express	The express Node.js module.
teddy	The teddy Node.js module.
formidable	The formidable Node.js module.
appName	The name of your app derived from package.json. Uses "Roosevelt Express" if no name is supplied.
appDir	The directory the main module is in.
package	The contents of package.json
staticsRoot	Full path on the file system to where your app's statics folder is located.
modelsPath	Full path on the file system to where your app's models folder is located.
viewsPath	Full path on the file system to where your app's views folder is located.
controllersPath	Full path on the file system to where your app's controllers folder is located.
params	The params you sent to Roosevelt.
port	Port Roosevelt is running on.
model	Method to return a model. Calling app.get('model')('modelName') will return a specified model from your models folder.

Warning: Roosevelt is beta software!

Not many apps have been written using Roosevelt yet, so it's entirely possible that there will be some significant bugs.

You should not use Roosevelt in production yet unless you're willing to devote some time to fixing any bugs you might find.

Help wanted!

Pull requests are welcome! Here are some things at the top of the to-do list at the moment:

• HTTPS support
• Support for more custom HTTP status code error pages
• Support for templating engines other than teddy
• Support for CSS preprocessors other than LESS
• Support for a client-side JS minifier (e.g. Google's Closure compiler)
• Probably many other things are needed too

Dependencies

• express - a minimal and flexible Node.js web application framework
• teddy - an easy-to-read, HTML-based, mostly logic-less DOM templating engine
• less-middleware - Connect middleware for LESS compiling
• formidable - a Node.js module for parsing form data, especially file uploads
• wrench - used by the CLI tool to help you create your sample app

License

All original code in Roosevelt is licensed under the Creative Commons Attribution 4.0 International License. Commercial and noncommercial use is permitted with attribution.