f5less

f5less (web) development

f5less lets you rebuild and reload your (web) project automagically after every ctrl-s!

f5less is platform/framework agnostic and open source.

Installation

You will need Java 7+ and a browser with websocket support (meaning anything except IE)1. Download one of

Linux/OS X f5less-0.1.1.tar.bz2 (08-24-2012)
Windows f5less-0.1.1.zip (08-24-2012)

extract the archive2 somewhere and add the extracted directory to the PATH.

Basics

Open a terminal in your project directory and run

1
f5less -js . ws:reload

this will start a websocket server on localhost:9999 that will monitor the '.' directory tree, and, because of the -js option, will create a f5less.js file to add to the pages for which you want dynamic reloading:3

1
2
<script type="text/javascript" src="f5less.js"></script>
<script type="text/javascript">f5less.connect()</script>

Every time you save a .css file all the css links in the page will be updated, while if you change an .htm, .html or .js file the page will be reloaded. This is just the default behavior that can be overridden by passing to f5less.connect a configuration object, for example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
f5less.connect({
    triggersCSSReload: function(filename) {
        return f5less.strEndsWith(filename, 
            ".css", ".png", ".jpg"
        );
    },

    triggersPageReload: function(filename) {
        return f5less.strEndsWith(filename, 
            ".js", ".html", ".htm", ".php"
        );
    }
});

f5less does more than that

f5less can also execute arbitrary commands on a filesystem change, for example it can compile a Markdown file to html using marked every time it's saved (assuming Windows, otherwise remove the .cmd)

1
f5less . "{-glob:**.md-}marked.cmd {p} > {p}.html"

where {p} will be replaced by the absolute path of the changed file upon invocation, while {-glob:**.md-} at the start is a filter.

Including

1
2
<script type="text/javascript" src="f5less.js"></script>
<script type="text/javascript">f5less.connect()</script>

in the Markdown leads to automatic page reload in addition to compilation by launching

1
f5less . ws:reload . "{-glob:**.md-}marked.cmd {p} > {p}.html"

in place of the previous command.

Specifics

In general f5less takes an arbitrary number of pairs path command, where path is the path to a directory and command is the command to run, following the rules exemplified in the previous section.

The commands will run in parallel. If you need sequencial processing on the same kind of files you probably want to create a script and use that with f5less.

Filters are tested against the path relative to the directory associated to the command and use the Java 7 PathMatcher syntax.

The {p} s inside a command are replaced with the absolute path of the changed entity.

Notification listeners are debounced, by default, on a 100ms interval (meaning that a command will run only after 100ms have passed since the last notification for its path). This is because, for example, you may receive multiple MODIFY events when saving a file, depending on the OS and on how the program writes it.

After a filesystem event the ws:reload server waits for all interested commands to run before sending notifications to clients.

That being said, filesystem notification is a bitchy subject so expect surprises.

To see the (few) available options just launch f5less without arguments.

Fork me on GitHub


  1. I'm thinking about creating a snippet for that parenthesis. 

  2. As usual on a *nix use the .tar.bz2, or use the .zip and change the permissions. 

  3. This will (should) work on any browser with websocket support.