Update documentation for bundling.

cespare · Jul 31, 2012 · 5787d06 · 5787d06
1 parent 5f6418c
commit 5787d06
Show file tree

Hide file tree

Showing 8 changed files with 81 additions and 19 deletions.
diff --git a/README.md b/README.md
@@ -1,12 +1,10 @@
-Pinion
-======
+# Pinion
 
 Pinion is a Rack application that serves assets, possibly transforming them in the process. It is generally
 useful for serving Javascript and CSS, and things that compile to Javascript and CSS such as Coffeescript and
 Sass.
 
-Goals
-=====
+# Goals
 
 There are a lot of tools that accomplish very similar things in this space. Pinion is meant to be a very
 simple and lightweight solution. It is driven by these core goals (bold goals are implemented):
@@ -17,15 +15,13 @@ simple and lightweight solution. It is driven by these core goals (bold goals ar
 * Recompile asynchronously from requests (no polling allowed)
 * **Compile assets one time in production**
 
-Installation
-============
+# Installation
 
     $ gem install pinion
 
 You should add pinion to your project's Gemfile.
 
-Usage
-=====
+# Usage
 
 The easiest way to use Pinion is to map your desired asset mount point to a `Pinion::Server` instance in your
 `config.ru`.
@@ -64,13 +60,57 @@ In your app, you will use pinion's helper methods to construct urls:
 <head>
   <title>My App</title>
   <link type="text/css" rel="stylesheet" href="<%= pinion.asset_url("/assets/style.css") %>" />
-  <!-- Shorthand equivalent -->
+  <%# Shorthand equivalent %>
   <%= pinion.css_url("style.css") %>
 </head>
 ```
 
-Notes
------
+# Production usage
+
+In production, you may wish to concatenate and minify your assets before you serve them. This is done through
+using asset bundles. Pinion provides a predefined bundle type, `:concatenate_and_uglify_js`, for your
+convenience.
+
+You can bundle files by putting this in your app:
+
+``` erb
+<%= @pinion.js_bundle(:concatenate_and_uglify_js, "main-bundle",
+    "app.js",
+    "helpers.js",
+    "util.js",
+    "jquery.js"
+    ) %>
+```
+
+In development, the individual `<script>` tags for each asset will be emitted; in production, a single asset
+(`main-bundle.js`) will be produced.
+
+The `:concatenate_and_uglify_js` bundle type simply concatenates JS files and runs them through
+[Uglifier](https://github.com/lautis/uglifier). No default CSS bundle type is provided (but the built-in Sass
+conversion type emits minified code in production, and typically you'll let Sass/Less/Stylus handle
+concatenation for you).
+
+You can define your own bundle types and their behavior if you like:
+
+``` ruby
+# The block is passed an array of `Pinion::Asset`s; it should return the content of the bundled files.
+Pinion::BundleType.create(:concatenate_js_only) do |assets|
+  # Demo code only; you need to be a bit more careful in reality. See the definition of
+  # :concatenate_and_uglify_js for hints.
+  assets.map(&:contents).join("\n")
+end
+```
+
+Note that in production mode, asset URLs will have the md5sum of the asset inserted into them:
+
+``` html
+<link type="text/css" rel="stylesheet" href="/assets/style-698f462d2f43890597ae78df8286d03f.css" />
+<script src="/assets/test-bundle-cd94852076ffa13c006cf575dfff9e35.js"></script>
+```
+
+and these assets are served with long (1-year) expiry, for good cacheability.
+
+# Notes
 
 * Currently, Pinion sidesteps the dependency question by invalidating its cache of each file of a particular
   type (say, all `.scss` files) when any such source file is changed.
@@ -79,15 +119,21 @@ Notes
   and `foo/baz/style.scss` exist, then `foo/bar/style.scss` will be used if a request occurs for
   `/style.css`.)
 
-You can see an example app using Pinion and Sinatra in the `example/` directory.
+You can see an example app using Pinion and Sinatra in the `example/` directory. Run `bundle install` in that
+directory to get the necessary gems, then run it:
+
+    rackup config.ru                     # Development mode
+    RACK_ENV=production rackup config.ru # Production mode
 
-Authors
-=======
+# Authors
 
 Pinion was written by Caleb Spare ([cespare](https://github.com/cespare)). Inspiration from
 [sprockets](https://github.com/sstephenson/sprockets).
 
-License
-=======
+Contributions from:
+
+* Alek Storm ([alekstorm](https://github.com/alekstorm))
+
+# License
 
 Pinion is released under [the MIT License](http://www.opensource.org/licenses/mit-license.php).
diff --git a/TODO.md b/TODO.md
@@ -4,4 +4,4 @@ TODO
 * Async recompilation (FSSM or something else?) in development
 * Figure out if there is a better way to let Pinion know its mount point, and for the app to talk to pinion.
   **Idea:** Construct the `Pinion::Server` instance in the app. This should be a much better way.
-* Move `find_asset` and friends to be `Asset` class methods.
+* Add some hints about nginx configuration to the readme.
diff --git a/example/Gemfile b/example/Gemfile
@@ -7,3 +7,5 @@ gem "rack"
 gem "sass"
 gem "slim"
 gem "rerun"
+gem "coffee-script"
+gem "uglifier"
diff --git a/example/Gemfile.lock b/example/Gemfile.lock
@@ -1,8 +1,15 @@
 GEM
   remote: http://rubygems.org/
   specs:
+    coffee-script (2.2.0)
+      coffee-script-source
+      execjs
+    coffee-script-source (1.1.2)
     daemons (1.1.8)
     eventmachine (0.12.10)
+    execjs (1.2.13)
+      multi_json (~> 1.0)
+    multi_json (1.1.0)
     rack (1.4.1)
     rack-protection (1.2.0)
       rack
@@ -21,14 +28,19 @@ GEM
       eventmachine (>= 0.12.6)
       rack (>= 1.0.0)
     tilt (1.3.3)
+    uglifier (1.2.4)
+      execjs (>= 0.3.0)
+      multi_json (>= 1.0.2)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  coffee-script
   rack
   rerun
   sass
   sinatra
   slim
   thin
+  uglifier
diff --git a/example/app.rb b/example/app.rb
@@ -22,6 +22,6 @@ def initialize(pinion)
   head
     title Sample App
     == @pinion.css_url("style.css")
-    == @pinion.js_url("uncompiled.js")
+    == @pinion.js_bundle(:concatenate_and_uglify_js, "test-bundle", "uncompiled.js", "compiled.js")
   body
     h3 Hello there! This text should be dark green.
diff --git a/example/config.ru b/example/config.ru
@@ -7,6 +7,7 @@ ASSET_MOUNT_POINT = "/assets"
 
 pinion = Pinion::Server.new(ASSET_MOUNT_POINT)
 pinion.convert :scss => :css
+pinion.convert :coffee => :js
 pinion.watch "scss"
 pinion.watch "javascripts"
 

diff --git a/example/javascripts/compiled.coffee b/example/javascripts/compiled.coffee
@@ -0,0 +1 @@
+console.log "hello from coffeescript!"
diff --git a/example/javascripts/uncompiled.js b/example/javascripts/uncompiled.js
@@ -1 +1 @@
-alert("hello!");
+console.log("hello from javascript!");