Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 164 lines (98 sloc) 4.913 kb
85b76be @serby Readme update
authored
1 # versionator - Static content versioning middleware for connect and express.
9f077cb @serby Adding readme
authored
2
2187672 @serby Adding travisci status image and twitter account
authored
3 [![build status](https://secure.travis-ci.org/serby/versionator.png)](http://travis-ci.org/serby/versionator)
4
a5c6a5a @serby Typos and adding maxAge
authored
5 versionator was built to solve the problem of static assets getting stuck in browser and proxy caches when new versions of the assets are deployed.
9f077cb @serby Adding readme
authored
6
7 Without versionator this is what can happen:
8
1ade932 @serby Adding irickt to credits
authored
9 You set your static content to be cached and expire in 30 days time.
a5c6a5a @serby Typos and adding maxAge
authored
10
11 express.static(__dirname + '/public', { maxAge: 2592000000 })
12
13 This gives you more capacity on your web servers and a better rating on Google Pagespeed and ySlow.
9f077cb @serby Adding readme
authored
14
0270e73 @serby Updating readme
authored
15 You deploy your site and all is good.
9f077cb @serby Adding readme
authored
16
a5c6a5a @serby Typos and adding maxAge
authored
17 Then you need to make a change to sprite.png or app.js
9f077cb @serby Adding readme
authored
18
5f00c04 @serby Update README.md
authored
19 You make your changes and redeploy. The trouble now is that everyone who has looked at your site already has the old version in their browser cache. Not only that, any upstream proxies will also have a copy.
9f077cb @serby Adding readme
authored
20
a5c6a5a @serby Typos and adding maxAge
authored
21 A possible solution is to rename your static assets every time you change them, but that is impractical as you also have to update all the references each time they change. If you have a single CSS sprite then this is a real pain.
9f077cb @serby Adding readme
authored
22
23 A better solution is to use versionator!
24
25 ## Installation
26
bc0526c @serby Updating readme
authored
27 npm install versionator
9f077cb @serby Adding readme
authored
28
29 ## Usage
30
16f6bdc @serby Adding examples
authored
31 ### Basic Middleware
32
1ade932 @serby Adding irickt to credits
authored
33 The simplest way to use versionator is to use the basic middleware which looks for the given
16f6bdc @serby Adding examples
authored
34 version number in a url path and strips it out.
35
9f077cb @serby Adding readme
authored
36 Add versionator into your middleware stack before the static middleware:
37
16f6bdc @serby Adding examples
authored
38 ```js
39
40 app.version = '0.1.0';
e8ea53c @bengourley Fixed tests. Added `create` alias for `createBasic`.
bengourley authored
41 var versionator = require('versionator').create(app.version);
9020273 @serby Updated with new example
authored
42
16f6bdc @serby Adding examples
authored
43 app.configure(function() {
9f077cb @serby Adding readme
authored
44
5d682ca @bengourley Further fix to readme
bengourley authored
45 app.use(versionator.middleware)
16f6bdc @serby Adding examples
authored
46 ....
47 .use(express.static(__dirname + '/public', { maxAge: 2592000000 }));
9f077cb @serby Adding readme
authored
48
16f6bdc @serby Adding examples
authored
49 });
9f077cb @serby Adding readme
authored
50
16f6bdc @serby Adding examples
authored
51 ```
9f077cb @serby Adding readme
authored
52
53 Public folder:
54
5f00c04 @serby Update README.md
authored
55 public/js/app.js
9f077cb @serby Adding readme
authored
56
57 In your HTML,CSS,JS add the version as an extra path.
58
59 e.g.
60 ### HTML
5f00c04 @serby Update README.md
authored
61 <script src='/js/v0.1.0/app.js' />
9f077cb @serby Adding readme
authored
62
1ade932 @serby Adding irickt to credits
authored
63 There is also a URL versioning helper that will convert paths for you.
16f6bdc @serby Adding examples
authored
64 You can expose as a helper like so:
65
66 ```js
67
68 app.configure(function() {
9f077cb @serby Adding readme
authored
69
16f6bdc @serby Adding examples
authored
70 // This exposes the helper to the views
71 app.helpers({
e8ea53c @bengourley Fixed tests. Added `create` alias for `createBasic`.
bengourley authored
72 versionPath: versionator.versionPath
16f6bdc @serby Adding examples
authored
73 });
74
75 });
76
77 ```
9f077cb @serby Adding readme
authored
78
79 ### Jade
80
16f6bdc @serby Adding examples
authored
81 This can then be used in Jade like so
82
83 script(src=versionPath(/js/app.js))
9f077cb @serby Adding readme
authored
84
16f6bdc @serby Adding examples
authored
85 ### Middleware
86
87 versionator middleware will strip URL path names containing the version string. req.url is then modified for all other middleware.
9f077cb @serby Adding readme
authored
88
89 e.g.
90
5f00c04 @serby Update README.md
authored
91 req.url = '/js/v0.1.0/app.js'
9f077cb @serby Adding readme
authored
92
93 will become:
94
5f00c04 @serby Update README.md
authored
95 req.url = '/js/app.js'
9f077cb @serby Adding readme
authored
96
5f00c04 @serby Update README.md
authored
97 Now all you need to do is increment app.version each deployment (We keep ours inline with our git tags using cake, the coffee-script build tool) then sit back and let your users enjoy the freshness.
9f077cb @serby Adding readme
authored
98
a5c6a5a @serby Typos and adding maxAge
authored
99 An example of how to use versionator with connect and express can be found in the examples folder.
9f077cb @serby Adding readme
authored
100
16f6bdc @serby Adding examples
authored
101 ### Mapped Middleware
102
103 You can also use versionator to add a hash, based on the content of the file, to the url path.
104 This way the url path will only change if the file has changed.
105
1ade932 @serby Adding irickt to credits
authored
106 To do this you must first create a hash for all the files in the public folder.
16f6bdc @serby Adding examples
authored
107 This can be done as the application starts or read from a file that is created on deployment.
108
109 ```js
110
111 versionator.createMapFromPath(__dirname + '/public', function(error, staticFileMap) {
112
113 var mappedVersion = versionator.createMapped(staticFileMap);
114
115 app.configure(function(){
116
117 // This exposes the helper to the views
118 app.helpers({
119 versionPath: mappedVersion.versionPath
120 });
121
122 app
123 .set('views', __dirname + '/views')
124 .set('view engine', 'jade')
125 .use(express.bodyParser())
126 .use(express.methodOverride())
127 .use(mappedVersion.middleware)
128 ....
129 });
130
131 ....
132 });
133 ```
653eb3e @serby Adding final line
authored
134 If you use the helper you can switch methods without any changes to your view code.
135
1d87928 @irickt document live map
irickt authored
136 ### Live map updates
137
138 You can modify the map at runtime, say if during development you want to do a live reload of a resource. First, get the hash map for the modified files by passing a list of files as a `fileList` parameter. This should be full file paths and the files should be in the original public directory. The directory is passed in as well. Then pass the the new hash map to the middleware via `modifyMap`. Then push the new url to the client and update the resource tag to cause a reload.
139
140 ```js
141
142 var mappedVersion = versionator.createMapped(originalFileMap);
143 ...
144 // modify resource files. put full file path(s) in a list.
1ade932 @serby Adding irickt to credits
authored
145
3b7eda6 @serby Update README.md
authored
146 versionator.createMapFromPath(__dirname + '/public', {'fileList': fileList}, function(error, modifiedFileMap) {
1d87928 @irickt document live map
irickt authored
147 mappedVersion.modifyMap(modifiedFileMap);
148 )};
1ade932 @serby Adding irickt to credits
authored
149
1d87928 @irickt document live map
irickt authored
150 // send new hashed path to client
151 hashedpath = mappedVersion.versionPath(path)
152 ...
153 ```
154
16f6bdc @serby Adding examples
authored
155
9f077cb @serby Adding readme
authored
156 ## Credits
1ade932 @serby Adding irickt to credits
authored
157
16f6bdc @serby Adding examples
authored
158 [Paul Serby](https://github.com/serby/) follow me on [twitter](http://twitter.com/PabloSerbo)
9f077cb @serby Adding readme
authored
159
1ade932 @serby Adding irickt to credits
authored
160 [Rick Thomas](https://github.com/irickt)
161
9f077cb @serby Adding readme
authored
162 ## Licence
163 Licenced under the [New BSD License](http://opensource.org/licenses/bsd-license.php)
Something went wrong with that request. Please try again.