An asset pipeline for clojure
Stefon is an asset pipeline for Clojure, closely modelled after Ruby's Sprockets. It is a rewrite of dieter.
Stefon is fast, easy to use, and easy to extend. It uses idiomatic clojure, and is written to support both development use (ie it is very fast), and production use (it precompiles for deployment to a CDN). Stefon's major selling points are speed, its ease of use in production and development, and its ability to support multiple languages and compressors.
Stefon is an asset pipeline. In production, it is used to precompile assets to be served by a CDN or via Ring's file-wrap middleware. In develepment mode, it serves files directly, recompiling them on changes.
Add stefon as a dependency in project.clj
:dependencies [[circleci/stefon "0.5.0-SNAPSHOT"]]
:plugins [[lein-stefon-precompile "0.5.0"]]
:jvm-opts ["-Djna.library.path=target/native/macosx/x86_64:target/native/linux/x86_64:target/native/linux/x86"]
Insert it into your ring middleware stack
(-> app
(stefon/asset-pipeline config-options))
Or if you use noir
(server/add-middleware stefon/asset-pipeline config-options)
Concatenation of assets is handled by a Stefon manifest file. A manifest is a file whose name ends in .stefon and whose contents are a clojure vector of file names / directories to concatenate.
For example, a file named assets/javascripts/app.js.stefon
with the following contents:
[
"./base.js"
"framework.js"
"./lib/"
"./models/"
]
Stefon would look for base.js in the same directory, and then concatenate each file from the lib and models directories. It concatenated all files in order. Directory contents are concatenated in alphabetical order.
Less files have one caveat at present: they read their imports directly from file system, without going through stefon. That means that you can't use .less.ref files. As a workaround, make your root file a .ref.less file, and do the assetifying after less compilation has finished.
To refer to other assets from your asset, use a .ref file. This allows you to write functions that reference other assets, such as data-uri and asset-path. If you're familiar with sprockets, this is similar to how you might use a .erb file.
There are some sharp edges here, at the moment. In particular, there is no dependency tracking, and caching compiled assets is very naive. This means if you refer to asset A from asset B, and then change A, B won't actually change unless you restart your program.
In order to include links to your assets you may use the link-to-asset function.
(link-to-asset "stylesheets/reset.css" config-options)
(link-to-asset "javascripts/app.js.stefon" config-options)
To use precompilation, we need to actually precompile files:
lein stefon-precompile
and then load the precompiled files
(defn init []
(stefon/init stefon-options))
The following configuration options are available.
;; Searched for assets in the order listed. Must have a directory called 'assets'.
:asset-roots ["resources"]
;; The root for compiled assets, which are written to (serving-root)/assets. In dev mode defaults to "/tmp/stefon")
:serving-root "public"
;; Set to :production to serve precompiled files, or when running `lein stefon-precompile`
:mode :development
;; Where the result of the precompile should be stored. Might be good to keep it out of the web root.
:manifest-file "manifest.json"
;; When precompiling, the list of files to precompile. Can take regexes (coming soon), which will attempt to match all files in the asset roots.
:precompiles ["./assets/myfile.js.stefon"]
Note you need to pass your config options to asset-pipeline
as well as link-to-asset
.
It is easy to add new preprocessors to stefon. Most asset types uses the default library for that language, hooked up to stefon using V8. See the source for easy-to-follow examples.
Distributed under the Eclipse Public License, the same as Clojure.
Mostly written by Paul Biggar from CircleCI. Based on a fork of dieter by John Andrews from EdgeCase. With contributions by many others.
lein stefon-precompile