Server Resources

Mimosa jump starts and integrates your server development

Mimosa's server support comes courtesy of the mimosa-server module. As such, it belongs to a codebase apart from the Mimosa core, and it behaves according to the rules of any Mimosa module, so it can be removed and added.

No server necessary

With mimosa watch Mimosa does not need to serve assets. A project might have a server already. mimosa watch is good with that. It'll run the workflow, compile code, lint it, write it, and stop there.

But if you want one...

Toss a -s/--server onto mimosa watch and Mimosa will invoke a server. Which server Mimosa invokes depends on what is in the mimosa-config. Mimosa could start its own embedded Express server and point it at a project's views and assets. Or Mimosa could start the server provided by mimosa new. Or Mimosa could execute an existing server using a simple exports hook.

All server integration options are nodejs-based. The server module does not have the ability to start your Rails server or your Tomcat. But Mimosa can deliver compiled assets to the directory your server expects to find them by changing the watch.compiledDir to that location.

Server

mimosa new provides the option to have a server or to use Mimosa's embedded server. If no server is chosen, Mimosa will not deliver any sort of server code.

If the Express option is chosen, Mimosa will provide a single file, written in the chosen JavaScript meta-language, that Mimosa will use to start your server. Mimosa also provides a simple router, also in the JavaScript meta-language you chose.

Views

mimosa new provides the option to select a server view technology. Plain HTML is an option as well as a number of dynamic templating technologies. Depending on the technology chosen, Mimosa will provide one or two view templates for the starter app.

Mimosa comes bundled with its own Express server. If server.defaultServer.enabled is set to true in the mimosa-config, then when mimosa watch is run with the --server flag, Mimosa will run its embedded server. When running Mimosa's Express, all of the settings in the server portion of the mimosa-config become very important. See the server configuration details to learn more.

Mimosa's Express will do a few things in addition to serving up an application. Assuming liveReload.enabled is set to true (default), Live Reload will be used. Mimosa will reload the browser whenever a file in liveReload.additionalDirs (default 'views') or config.watch.compiledDir (default 'public') changes. Mimosa will also serve static assets gzipped.

Routing

How Mimosa routes a project's paths depends on the setting for server.defaultServer.onePager.

When onePager is set to true the embedded Express server is configured to automatically route every request to the application's index view that doesn't result in an asset being returned. For instance given a URL of/account/1/item/2/comment/4 Mimosa's embedded server will route the request to the index view and leave the handling of the complex URL to the client code.

When onePager is set to false, Mimosa will assume simple routes for the application. url:3000/ will still route to the index view. Buturl:3000/foo/ will route to the foo view as will url:3000/foo/bar/baz.

Mimosa can start a nodejs based server. If server.defaultServer.enabled is set to false, Mimosa will look for a piece of node.js code located at server.path, and execute the startServer function of that code (so that function must be exported). That function will be passed the entire resolved and enriched mimosa-config.

The startServer function is also passed a callback that must be executed for Mimosa to continue through its workflows. If using Mimosa's live reload functionality is being used, the callback should be provided node's http server object as a first parameter. That happens to be the object returned by Express's app.listen() function. If socket.io is being used, then the callback should be provided the socket.io object as a second parameter. See the Live Reload section on the Utilities page for more details.

The server code delivered by mimosa new will use all of the configuration from the mimosa-config server block. The use of the mimosa-config entries could be removed from the delivered code. For instance, in the following code, all of the bolded entries could be replaced with their actual values, but this of course means Mimosa will be less capable of controlling behavior an app.

app.configure ->
  app.set 'port', config.server.port
  app.set 'views', config.server.views.path
  app.engine config.server.views.extension, engines[config.server.views.compileWith]
  app.set 'view engine', config.server.views.extension

One of the options when running mimosa new is to choose no server. The mimosa-config that Mimosa delivers when you choose this option includes no mimosa-server or mimosa-live-reload because both of those modules involve using either a node.js custom server or Mimosa's embedded Express server.

Choose no server when either one is legitimately not needed, or when a non-node.js server already exists and needs to be leveraged. An an example I've experienced teams using Mimosa on top of node.js, Rails/Sinatra, and .NET backends.

When running a non-node.js server, the major consideration is the watch.compiledDir. The output of asset compilation might need to redirected to another folder where the server lives. Consider the following:

watch:
  compiledDir: "../server/public"

This setup will place the compiled assets up one level and then into a server/public directory. Sitting alongside the server directory might be a client directory where all the Mimosa managed UI code lives.

As with the server code Mimosa delivers, the view code and routes are built to be flexible enough to work in several scenarios. Some conditionals and mimosa-config properties can be replaced or hard-coded. The code may not need that level of complexity.

Mimosa uses consolidate, both internally and within the delivered Express, to easily toggle between different view templating libraries. Also installed will be the library for the chosen templating library.

server.views.compileWith can be configured to use one of the available libraries, and each library has a default extension. When a client library is chosen during mimosa new, Mimosa will modify the mimosa-config with these values. The server.views.compileWith values are listed below next to the name of each technology. The default extensions are listed as well.

Jade jade .jade

Jade is available. The project that mimosa new delivers will include simple layout and index pages.

EJS ejs .ejs

EJS is also available, and mimosa new delivers a single index.ejs file.

Hogan hogan .hjs

Hogan is available, and mimosa new delivers a single index.hjs file.

Handlebars handlebars .hbs

Handlebars is available, and mimosa new delivers a single index.hbs file.

Dust dust .dust

Dust is available, and mimosa new delivers a single index.dust file.

HTML html .html

Plain HTML templates can be chosen too. Mimosa uses EJS behind the scenes (see above), as EJS allows plain HTML pages. To accommodate the fact that plain HTML isn't dynamic, if plain HTML templating is chosen, mimosa new provides two templates, one each for running with and without the optimize flag. The Express routes know how to toggle between the two. Also, the delivered server has a switch in its options for Live Reload that will allow plain HTML pages to work just fine, so not having that dynamic toggle in a view will not cause any trouble.