Polyvalent cephalopod mollusc. (aka ambitious app assember)

What the ★★★★?

Polvo is a built system and an application assembler for the browser.

Yet another one.

Dependency Resolution

Polvo uses the same resolution algorithm presented in NodeJS, so you can code your libraries doing global or local require-s as you wish, like if you were building a NodeJS app. In the end, everything will be ready for in-browser use.

★ Of couse, you won't be able to use NodeJS core modules once inside the Browser, such as fs, process, cluster and so on. The same applies to any other module you may find - if it uses any API not available for in-browser use, you won't be able to use it.

Packaging Systems

In order to not lock you up with one single packaging system, Polvo is intended to support some of them. It's not fully functional yet but the plans are there.

★ As each packaging system approaches the subject in its own opinionated way, it may be impossible to aggregate them all in an universal way. However its under serious study and implementation right now to check all possibilities.

At the moment you can use:

  • NPM Full support, hooray!
  • Component Partial support [1]
  • Bower Partial support, with some caveats [2]
  • Ender Yet to be done [3]

[1] Supporting only js and css for now, full implementation is a WIP
[2] TODO: Describe caveats
[3] Pondering the real benefits and possibilities of implementing Ender

Plugins (supported languages)

Again, Polvo is agnostic to languages -- however it needs individual plugins for each language in order to properly assemble it. Some of them is built in out of the box for you joy, and others should be done / installed separately.

Polvo will search and initialize aditional plugins present in the dependencies field of your package.json file.

Each plugin is an independent repository.

Click the links to see individual README for each one.

  1. Javascript (.js)
  2. CoffeeScript (.coffee)
    • ✓ Literate Coffeescript (.litcoffee, .coffee.md)
    • ✓ Source Maps
  1. CSS (.css)
    • partials supported
  2. Stylus (.styl)
    • nib available
    • partials supported
  1. HTML (.htm, .html)
    • partials supported
  2. Jade (.jade)
    • partials supported


Command line interface help screen.

  polvo [options] [params]
  -w, --watch        Start watching/compiling in dev mode                
  -c, --compile      Compile project in development mode                 
  -r, --release      Compile project in release mode                     
  -s, --server       Serves project statically, options in config file   
  -f, --config-file  Path to a different config file                     
  -b, --base         Path to app's root folder (when its not the current)
  -x, --split        Compile files individually - useful for tests coverage
  -v, --version      Show Polvo's version                                
  -h, --help         Shows this help screen                              
  polvo -c
  polvo -cs
  polvo -w
  polvo -ws
  polvo -wsf custom-config-file.yml


Polvo's config file is simply a file named polvo.yml in your project.

You'll may need to setup six simple options to adjust Polvo to your needs:

  1. server
  2. input
  3. output
  4. alias
  5. minify
  6. boot

A Polvo's complete config file look such as:

  port: 3000
  root: ./public
  - src
  js: ./public/app.js
  css: ./public/app.css
  app: ./src/app
  js: false
  css: false
boot: ./src/app/app

Basic infos to serve your application, just inform desired port and your public folder.

When using the option -s a basic webserver will be launched to serve the app.

Project's input src folders, can be one or many.

Project's output files, at least one should be specified.

★ If you're using conditional compilation, make sure you're aware that you can reuse the conditional [variables]((#final-notes) to compose the output path for your files.

It's a handy option that lets you map some names to specific dirs. These names will make folders act like gobal modules in your node_modules folder with all dirs listed in package.json directories field, so you can require them as such.

For example, imagine a structure like this:

├── polvo.yml
├── src
│   └── app
│       ├── app.coffee
│       ├── controllers
│       │   └── controller.coffee
│       ├── models
│       │   └── model.coffee
│       └── views
│           └── views.coffee
└── vendors
    └── myframework
        └── src
            └── lib
                ├── controller.coffee
                ├── model.coffee
                └── view.coffee

The app's controller.coffee can require the framework's controller.coffee as easy as:

Controller = require '../../../vendors/myframework/src/lib/controller'

However, sometimes these relative paths can get nasty. In these cases, aliases can help the way. Imagine this one:

  myframework: ./vendors/myframework/src

With this, myframework folder will act as if it was a NPM module present in your node_modules folder, and require calls can be made in global-style regardless of which file is requiring it:

Controller = require 'myframework/lib/controller'

Note that:

  1. The myframework keywork is the virtual alias in the config file
  2. It points to the folder vendors/myframework/src
  3. So requiring myframewok/**/* will be the same as requiring vendors/myframework/src/**/*
  4. Be cautious while using aliases. For instance if you have have an alias with the same name of a module you have in your node_modules folder, you'll end up with serious problems - hopefully you'll notice this immediately.

In some cases you may want to disable minification in release mode, even though in both development and release mode you'll always have a single .js and .css file.

So what's the catch?

In development mode other things will be injected among your scripts in the app.js file. For example, the LiveReload embedded functionality.

In release mode it's removed, nothing special is injected. So you may want to have a production ready release file (that doesn't includes magic), but at the same time keep it uncompressed. In case you do, that's the way to go.

By default, Polvo will wrap all your scripts and templates in CJS module and register them all at startup. However, none will be require-d and therefore none will be initialized.

You need to specify your app's entry point within the boot property. With this Polvo will do a simple require to this file at startup, after everything is registered.

Following the config presented above, it'd be:

require( 'src/app/app' );