I recently had a bad experience with an open source library. My own open source library, Asset Rack. It wasn't a documentation problem or a bug or anything like that. It was something more abstract that tripped me up.

Here's what happened. I was setting up a new project with Asset Rack like I normally do:

rack = require 'asset-rack'

assets = new rack.AssetRack [
    new rack.LessAsset
        url: '/style.css'
        filename: './style/core.less'
]

assets.on 'complete', ->
    app = require('express')()
    app.use assets
    app.listen 7076

Now, it's very clear in the docs (that I myself wrote) that Asset Rack is going to hash that style.css url so that it is going to look something like this style-as90a80adbac9d83e09ds.css. It does this for versioning, caching, conflict resolution, speed, blah blah blah. It's important...

But for some reason, I really thought that my resource was going to be located at /style.css. So I wasted time energy and got myself all frustrated, because it wasn't working like I should have known that it wasn't going to work.

That's when it hit me.

It's too complicated! Simplify, simplify, simplify.

And that's when you know it's time for a rewrite. So now, you can do the above like this.

rack = require 'asset-rack'
app = require('express')()app.use new rack.LessAsset
url: '/style.css'
filename: './style/core.less'

app.listen 7076

Much simpler, and now:

• By default hashed and unhashed urls are both available.
• For single asset projects, you don't need a rack.
• No more waiting for the complete callback.

There were a lot of other really cool updates with this release, so if you have the time, then check it out.