sprockets 3.7.2 → 4.0.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +47 -267
- data/README.md +477 -321
- data/bin/sprockets +11 -7
- data/lib/rake/sprocketstask.rb +3 -2
- data/lib/sprockets.rb +99 -39
- data/lib/sprockets/add_source_map_comment_to_asset_processor.rb +60 -0
- data/lib/sprockets/asset.rb +31 -23
- data/lib/sprockets/autoload.rb +5 -0
- data/lib/sprockets/autoload/babel.rb +8 -0
- data/lib/sprockets/autoload/closure.rb +1 -0
- data/lib/sprockets/autoload/coffee_script.rb +1 -0
- data/lib/sprockets/autoload/eco.rb +1 -0
- data/lib/sprockets/autoload/ejs.rb +1 -0
- data/lib/sprockets/autoload/jsminc.rb +8 -0
- data/lib/sprockets/autoload/sass.rb +1 -0
- data/lib/sprockets/autoload/sassc.rb +8 -0
- data/lib/sprockets/autoload/uglifier.rb +1 -0
- data/lib/sprockets/autoload/yui.rb +1 -0
- data/lib/sprockets/autoload/zopfli.rb +7 -0
- data/lib/sprockets/babel_processor.rb +66 -0
- data/lib/sprockets/base.rb +49 -12
- data/lib/sprockets/bower.rb +5 -2
- data/lib/sprockets/bundle.rb +40 -4
- data/lib/sprockets/cache.rb +36 -1
- data/lib/sprockets/cache/file_store.rb +25 -3
- data/lib/sprockets/cache/memory_store.rb +9 -0
- data/lib/sprockets/cache/null_store.rb +8 -0
- data/lib/sprockets/cached_environment.rb +14 -19
- data/lib/sprockets/closure_compressor.rb +1 -0
- data/lib/sprockets/coffee_script_processor.rb +18 -4
- data/lib/sprockets/compressing.rb +43 -3
- data/lib/sprockets/configuration.rb +3 -7
- data/lib/sprockets/context.rb +97 -24
- data/lib/sprockets/dependencies.rb +1 -0
- data/lib/sprockets/digest_utils.rb +25 -5
- data/lib/sprockets/directive_processor.rb +45 -35
- data/lib/sprockets/eco_processor.rb +1 -0
- data/lib/sprockets/ejs_processor.rb +1 -0
- data/lib/sprockets/encoding_utils.rb +1 -0
- data/lib/sprockets/environment.rb +9 -4
- data/lib/sprockets/erb_processor.rb +28 -21
- data/lib/sprockets/errors.rb +1 -0
- data/lib/sprockets/exporters/base.rb +71 -0
- data/lib/sprockets/exporters/file_exporter.rb +24 -0
- data/lib/sprockets/exporters/zlib_exporter.rb +33 -0
- data/lib/sprockets/exporters/zopfli_exporter.rb +14 -0
- data/lib/sprockets/exporting.rb +73 -0
- data/lib/sprockets/file_reader.rb +1 -0
- data/lib/sprockets/http_utils.rb +25 -7
- data/lib/sprockets/jsminc_compressor.rb +32 -0
- data/lib/sprockets/jst_processor.rb +11 -10
- data/lib/sprockets/loader.rb +87 -67
- data/lib/sprockets/manifest.rb +64 -62
- data/lib/sprockets/manifest_utils.rb +9 -6
- data/lib/sprockets/mime.rb +8 -42
- data/lib/sprockets/npm.rb +52 -0
- data/lib/sprockets/path_dependency_utils.rb +3 -11
- data/lib/sprockets/path_digest_utils.rb +2 -1
- data/lib/sprockets/path_utils.rb +87 -7
- data/lib/sprockets/paths.rb +1 -0
- data/lib/sprockets/preprocessors/default_source_map.rb +49 -0
- data/lib/sprockets/processing.rb +31 -61
- data/lib/sprockets/processor_utils.rb +24 -35
- data/lib/sprockets/resolve.rb +177 -93
- data/lib/sprockets/sass_cache_store.rb +2 -6
- data/lib/sprockets/sass_compressor.rb +13 -1
- data/lib/sprockets/sass_functions.rb +1 -0
- data/lib/sprockets/sass_importer.rb +1 -0
- data/lib/sprockets/sass_processor.rb +30 -9
- data/lib/sprockets/sassc_compressor.rb +56 -0
- data/lib/sprockets/sassc_processor.rb +297 -0
- data/lib/sprockets/server.rb +26 -23
- data/lib/sprockets/source_map_processor.rb +66 -0
- data/lib/sprockets/source_map_utils.rb +483 -0
- data/lib/sprockets/transformers.rb +63 -35
- data/lib/sprockets/uglifier_compressor.rb +21 -11
- data/lib/sprockets/unloaded_asset.rb +13 -11
- data/lib/sprockets/uri_tar.rb +1 -0
- data/lib/sprockets/uri_utils.rb +11 -8
- data/lib/sprockets/utils.rb +41 -74
- data/lib/sprockets/utils/gzip.rb +46 -14
- data/lib/sprockets/version.rb +2 -1
- data/lib/sprockets/yui_compressor.rb +1 -0
- metadata +127 -23
- data/LICENSE +0 -21
- data/lib/sprockets/coffee_script_template.rb +0 -17
- data/lib/sprockets/deprecation.rb +0 -90
- data/lib/sprockets/eco_template.rb +0 -17
- data/lib/sprockets/ejs_template.rb +0 -17
- data/lib/sprockets/engines.rb +0 -92
- data/lib/sprockets/erb_template.rb +0 -11
- data/lib/sprockets/legacy.rb +0 -330
- data/lib/sprockets/legacy_proc_processor.rb +0 -35
- data/lib/sprockets/legacy_tilt_processor.rb +0 -29
- data/lib/sprockets/sass_template.rb +0 -19
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: a4743994bc846327ac80bde662aa5a26fd95ce5cca2dd149deafe0fe94b6bf00
|
|
4
|
+
data.tar.gz: 454485ef7d2c5aac60c69b7d7042ed1b74245afecfeadc72c7e9bc290dc8b5b8
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: c6d61894b3f53a76bf1f04c3f2fe74143b33e43d5fbdc3db216bdf0ad88d06f8a73fc61bd12071ee79e8aab49b36cb14685f6bb2d86582387cbc5522cef305a3
|
|
7
|
+
data.tar.gz: ca2bff624116f6de55ce4f9c6371be9d71245d2883c4837cf5a1b4969006fbdf8507b358c7986cccb03edb00711367538176ed2701a1e725cde1206163c64e2c
|
data/CHANGELOG.md
CHANGED
|
@@ -1,296 +1,76 @@
|
|
|
1
|
-
**
|
|
1
|
+
**Master**
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Get upgrade notes from Sprockets 3.x to 4.x at https://github.com/rails/sprockets/blob/master/UPGRADING.md
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## 4.0.2
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
- Fix `etag` and digest path compilation that were generating string with invalid digest since 4.0.1.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
## 4.0.1
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
- Fix for Ruby 2.7 keyword arguments warning in `base.rb`. [#660](https://github.com/rails/sprockets/pull/660)
|
|
12
|
+
- Fix for when `x_sprockets_linecount` is missing from a source map.
|
|
13
|
+
- Fix subresource integrity to match the digest of the asset.
|
|
12
14
|
|
|
13
|
-
|
|
15
|
+
## 4.0.0
|
|
14
16
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
* Fixed uglifier comment stripping #326
|
|
18
|
-
* Error messages now show load path info #313
|
|
17
|
+
- Fixes for Ruby 2.7 keyword arguments warnings [#625](https://github.com/rails/sprockets/pull/625)
|
|
18
|
+
- Manifest files are sorted alphabetically [#626](https://github.com/rails/sprockets/pull/626)
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
## 4.0.0.beta10
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
- Fix YACB (Yet Another Caching Bug) [Fix broken expansion of asset link paths](https://github.com/rails/sprockets/pull/614)
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
## 4.0.0.beta9
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
- Minimum Ruby version for Sprockets 4 is now 2.5+ which matches minimum ruby verision of Rails [#604]
|
|
27
|
+
- Fix threading bug introduced in Sprockets 4 [#603]
|
|
28
|
+
- Warn when two potential manifest files exist. [#560]
|
|
27
29
|
|
|
28
|
-
|
|
30
|
+
## 4.0.0.beta8
|
|
29
31
|
|
|
30
|
-
|
|
31
|
-
* Fix the list of compressable mime types.
|
|
32
|
-
* Improve performance of the `FileStore` cache.
|
|
32
|
+
- Security release for [CVE-2018-3760](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-3760)
|
|
33
33
|
|
|
34
|
-
|
|
34
|
+
## 4.0.0.beta7
|
|
35
35
|
|
|
36
|
-
|
|
37
|
-
|
|
36
|
+
- Fix a year long bug that caused `Sprockets::FileNotFound` errors when the asset was present [#547]
|
|
37
|
+
- Raise an error when two assets such as foo.js and foo.js.erb would produce the same output artifact (foo.js) [#549 #530]
|
|
38
|
+
- Process `*.jst.eco.erb` files with ERBProcessor
|
|
38
39
|
|
|
39
|
-
|
|
40
|
+
## 4.0.0.beta6
|
|
40
41
|
|
|
41
|
-
|
|
42
|
+
- Fix source map line offsets [#515]
|
|
43
|
+
- Return a `400 Bad Request` when the path encoding is invalid. [#514]
|
|
42
44
|
|
|
43
|
-
|
|
45
|
+
## 4.0.0.beta5
|
|
44
46
|
|
|
45
|
-
|
|
47
|
+
- Reduce string allocations
|
|
48
|
+
- Source map metadata uses compressed form specified by the [source map v3 spec](https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k). [#402] **[BREAKING]**
|
|
49
|
+
- Generate [index maps](https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit#heading=h.535es3xeprgt) when decoding source maps isn't necessary. [#402]
|
|
50
|
+
- Remove fingerprints from source map files. [#402]
|
|
46
51
|
|
|
47
|
-
|
|
52
|
+
## 4.0.0.beta4
|
|
48
53
|
|
|
49
|
-
|
|
54
|
+
- Changing the version now busts the digest of all assets [#404]
|
|
55
|
+
- Exporter interface added [#386]
|
|
56
|
+
- Using ENV vars in templates will recompile templates when the env vars change. [#365]
|
|
57
|
+
- Source maps for imported sass files with sassc is now fixed [#391]
|
|
58
|
+
- Load paths now in error messages [#322]
|
|
59
|
+
- Cache key added to babel processor [#387]
|
|
60
|
+
- `Environment#find_asset!` can now be used to raise an exception when asset could not be found [#379]
|
|
50
61
|
|
|
51
|
-
|
|
62
|
+
## 4.0.0.beta3
|
|
52
63
|
|
|
53
|
-
|
|
64
|
+
- Source Map fixes [#255] [#367]
|
|
65
|
+
- Performance improvements
|
|
54
66
|
|
|
55
|
-
|
|
67
|
+
## 4.0.0.beta2
|
|
56
68
|
|
|
57
|
-
|
|
69
|
+
- Fix load_paths on Sass processors [#223]
|
|
58
70
|
|
|
59
|
-
**3.3.4** (September 1, 2015)
|
|
60
71
|
|
|
61
|
-
|
|
72
|
+
## 4.0.0.beta1
|
|
62
73
|
|
|
63
|
-
|
|
74
|
+
- Initial release of Sprockets 4
|
|
64
75
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
**3.3.2** (August 19, 2015)
|
|
68
|
-
|
|
69
|
-
* Fix cache contents to use relative paths instead of absolute paths.
|
|
70
|
-
|
|
71
|
-
**3.3.1** (August 15, 2015)
|
|
72
|
-
|
|
73
|
-
* Fix legacy Tilt integration when locals is required argument.
|
|
74
|
-
|
|
75
|
-
**3.3.0** (August 12, 2015)
|
|
76
|
-
|
|
77
|
-
* Change internal cache key to use relative asset paths instead of absolute paths.
|
|
78
|
-
|
|
79
|
-
**3.2.0** (June 2, 2015)
|
|
80
|
-
|
|
81
|
-
* Updated SRI integrity to align with spec changes
|
|
82
|
-
* Deprecated Manifest integrity attribute
|
|
83
|
-
* Cleanup concatenating JS sources with newlines
|
|
84
|
-
|
|
85
|
-
**3.1.0** (May 10, 2015)
|
|
86
|
-
|
|
87
|
-
* Removed "index" logical path normalization. Asset#logical_path is always the
|
|
88
|
-
full logical path to the index file.
|
|
89
|
-
* Fixed static asset mtimes
|
|
90
|
-
* Fix manifest cleanup by age
|
|
91
|
-
* Removed redundant minifier level cache
|
|
92
|
-
* Updated SRI format according to spec changes
|
|
93
|
-
|
|
94
|
-
**3.0.3** (April 27, 2015)
|
|
95
|
-
|
|
96
|
-
* Fix static asset mtime fallback
|
|
97
|
-
* Only warn when specified asset version can not be loaded.
|
|
98
|
-
|
|
99
|
-
**3.0.2** (April 22, 2015)
|
|
100
|
-
|
|
101
|
-
* Ensure legacy Tilt handlers return String class data. Fixes issues with Haml
|
|
102
|
-
Tilt handler.
|
|
103
|
-
* Type check and improve error messages raised on bad processor returned results.
|
|
104
|
-
* Improve error message for relative paths not under load path.
|
|
105
|
-
* Changed HTML encoding fallback from ISO-8859-1 to default external.
|
|
106
|
-
* Avoid falling back to 0 mtimes which may cause warnings with tar
|
|
107
|
-
|
|
108
|
-
**3.0.1** (April 14, 2015)
|
|
109
|
-
|
|
110
|
-
* Fixed `Context#depend_on` with paths outside the load path
|
|
111
|
-
|
|
112
|
-
**3.0.0** (April 12, 2015)
|
|
113
|
-
|
|
114
|
-
[Guide to upgrading from Sprockets 2.x to 3.x](https://github.com/rails/sprockets/blob/3.x/UPGRADING.md)
|
|
115
|
-
|
|
116
|
-
* New processor API. Tilt interface is deprecated.
|
|
117
|
-
* Improved file store caching backend.
|
|
118
|
-
* MIME Types now accept charset custom charset detecters. Improves support for UTF-16/32 files.
|
|
119
|
-
* Environment#version no longer affects asset digests. Only used for busting the asset cache.
|
|
120
|
-
* Removed builtin support for LESS.
|
|
121
|
-
* Removed `//= include` directive support.
|
|
122
|
-
* Deprecated `BundledAsset#to_a`. Use `BundledAsset#included` to access debugging subcomponents.
|
|
123
|
-
* Support circular dependencies. For parity with ES6 modules.
|
|
124
|
-
* Manifest compilation will no longer generate .gz files by default. [Mixing
|
|
125
|
-
Content-Encoding and ETags is just a bad
|
|
126
|
-
idea](https://issues.apache.org/bugzilla/show_bug.cgi?id=39727)
|
|
127
|
-
* Added linked or referenced assets. When an asset is compiled, any of its links will be compiled as well.
|
|
128
|
-
* Introduce some limitations around enumerating all logical paths. 4.x will deprecate it and favor linked manifests for compliation.
|
|
129
|
-
* Add Asset integrity attribute for Subresource Integrity
|
|
130
|
-
* Default digest changed to SHA256. Configuring `digest_class` is deprecated.
|
|
131
|
-
* Rename `Asset#digest` to `Asset#hexdigest`. `Asset#digest` is deprecated and will
|
|
132
|
-
return a raw byte String in 4.x.
|
|
133
|
-
* Added transitional compatibility flag to `Environment#resolve(path, compat: true)`. 2.x mode operates with `compat: true` and 4.x with `compat: false`
|
|
134
|
-
* `manifest-abc123.json` renamed to `.sprockets-abc123.json`
|
|
135
|
-
|
|
136
|
-
**2.12.3** (October 28, 2014)
|
|
137
|
-
|
|
138
|
-
* Security: Fix directory traversal bug in development mode server.
|
|
139
|
-
|
|
140
|
-
**2.12.2** (September 5, 2014)
|
|
141
|
-
|
|
142
|
-
* Ensure internal asset lookups calls are still restricted to load paths within
|
|
143
|
-
asset compiles. Though, you should not depend on internal asset resolves to be
|
|
144
|
-
completely restricted for security reasons. Assets themselves should be
|
|
145
|
-
considered full scripting environments with filesystem access.
|
|
146
|
-
|
|
147
|
-
**2.12.1** (April 17, 2014)
|
|
148
|
-
|
|
149
|
-
* Fix making manifest target directory when its different than the output directory.
|
|
150
|
-
|
|
151
|
-
**2.12.0** (March 13, 2014)
|
|
152
|
-
|
|
153
|
-
* Avoid context reference in SassImporter hack so its Marshallable. Fixes
|
|
154
|
-
issues with Sass 3.3.x.
|
|
155
|
-
|
|
156
|
-
**2.11.0** (February 19, 2014)
|
|
157
|
-
|
|
158
|
-
* Cache store must now be an LRU implementation.
|
|
159
|
-
* Default digest changed to SHA1. To continue using MD5.
|
|
160
|
-
`env.digest_class = Digest::MD5`.
|
|
161
|
-
|
|
162
|
-
**2.10.0** (May 24, 2013)
|
|
163
|
-
|
|
164
|
-
* Support for `bower.json`
|
|
165
|
-
|
|
166
|
-
**2.9.3** (April 20, 2013)
|
|
167
|
-
|
|
168
|
-
* Fixed sass caching bug
|
|
169
|
-
|
|
170
|
-
**2.9.2** (April 8, 2013)
|
|
171
|
-
|
|
172
|
-
* Improve file freshness check performance
|
|
173
|
-
* Directive processor encoding fixes
|
|
174
|
-
|
|
175
|
-
**2.9.1** (April 6, 2013)
|
|
176
|
-
|
|
177
|
-
* Support for Uglifier 2.x
|
|
178
|
-
|
|
179
|
-
**2.9.0** (February 25, 2013)
|
|
180
|
-
|
|
181
|
-
* Write out gzipped variants of bundled assets.
|
|
182
|
-
|
|
183
|
-
**2.8.2** (December 10, 2012)
|
|
184
|
-
|
|
185
|
-
* Fixed top level Sass constant references
|
|
186
|
-
* Fixed manifest logger when environment is disabled
|
|
187
|
-
|
|
188
|
-
**2.8.1** (October 31, 2012)
|
|
189
|
-
|
|
190
|
-
* Fixed Sass importer bug
|
|
191
|
-
|
|
192
|
-
**2.8.0** (October 16, 2012)
|
|
193
|
-
|
|
194
|
-
* Allow manifest location to be separated from output directory
|
|
195
|
-
* Pass logical path and absolute path to each_logical_path iterator
|
|
196
|
-
|
|
197
|
-
**2.7.0** (October 10, 2012)
|
|
198
|
-
|
|
199
|
-
* Added --css-compressor and --js-compressor command line flags
|
|
200
|
-
* Added css/js compressor shorthand
|
|
201
|
-
* Change default manifest.json filename to be a randomized manifest-16HEXBYTES.json
|
|
202
|
-
* Allow nil environment to be passed to manifest
|
|
203
|
-
* Allow manifest instance to be set on rake task
|
|
204
|
-
|
|
205
|
-
**2.6.0** (September 19, 2012)
|
|
206
|
-
|
|
207
|
-
* Added bower component.json require support
|
|
208
|
-
|
|
209
|
-
**2.5.0** (September 4, 2012)
|
|
210
|
-
|
|
211
|
-
* Fixed Ruby 2.0 RegExp warning
|
|
212
|
-
* Provide stubbed implementation of context *_path helpers
|
|
213
|
-
* Add SassCompressor
|
|
214
|
-
|
|
215
|
-
**2.4.5** (July 10, 2012)
|
|
216
|
-
|
|
217
|
-
* Tweaked some logger levels
|
|
218
|
-
|
|
219
|
-
**2.4.4** (July 2, 2012)
|
|
220
|
-
|
|
221
|
-
* Canonicalize logical path extensions
|
|
222
|
-
* Check absolute paths passed to depend_on
|
|
223
|
-
|
|
224
|
-
**2.4.3** (May 16, 2012)
|
|
225
|
-
|
|
226
|
-
* Exposed :sprockets in sass options
|
|
227
|
-
* Include dependency paths in asset mtime
|
|
228
|
-
|
|
229
|
-
**2.4.2** (May 7, 2012)
|
|
230
|
-
|
|
231
|
-
* Fixed MultiJson feature detect
|
|
232
|
-
|
|
233
|
-
**2.4.1** (April 26, 2012)
|
|
234
|
-
|
|
235
|
-
* Fixed MultiJson API change
|
|
236
|
-
* Fixed gzip mtime
|
|
237
|
-
|
|
238
|
-
**2.4.0** (March 27, 2012)
|
|
239
|
-
|
|
240
|
-
* Added global path registry
|
|
241
|
-
* Added global processor registry
|
|
242
|
-
|
|
243
|
-
**2.3.2** (March 26, 2012)
|
|
244
|
-
|
|
245
|
-
* Fix Context#logical_path with dots
|
|
246
|
-
|
|
247
|
-
**2.3.1** (February 11, 2012)
|
|
248
|
-
|
|
249
|
-
* Added bytesize to manifest
|
|
250
|
-
* Added Asset#bytesize alias
|
|
251
|
-
* Security: Check path for forbidden access after unescaping
|
|
252
|
-
|
|
253
|
-
**2.3.0** (January 16, 2012)
|
|
254
|
-
|
|
255
|
-
* Added special Sass importer that automatically tracks any `@import`ed files.
|
|
256
|
-
|
|
257
|
-
**2.2.0** (January 10, 2012)
|
|
258
|
-
|
|
259
|
-
* Added `sprockets` command line utility.
|
|
260
|
-
* Added rake/sprocketstask.
|
|
261
|
-
* Added json manifest log of compiled assets.
|
|
262
|
-
* Added `stub` directive that allows you to exclude files from the bundle.
|
|
263
|
-
* Added per environment external encoding (Environment#default_external_encoding). Defaults to UTF-8. Fixes issues where LANG is not set correctly and Rubys default external is set to ASCII.
|
|
264
|
-
|
|
265
|
-
**2.1.2** (November 20, 2011)
|
|
266
|
-
|
|
267
|
-
* Disabled If-Modified-Since server checks. Fixes some browser caching issues when serving the asset body only. If-None-Match caching is sufficient.
|
|
268
|
-
|
|
269
|
-
**2.1.1** (November 18, 2011)
|
|
270
|
-
|
|
271
|
-
* Fix windows absolute path check bug.
|
|
272
|
-
|
|
273
|
-
**2.1.0** (November 11, 2011)
|
|
274
|
-
|
|
275
|
-
* Directive comment lines are now turned into empty lines instead of removed. This way line numbers in
|
|
276
|
-
CoffeeScript syntax errors are correct.
|
|
277
|
-
* Performance and caching bug fixes.
|
|
278
|
-
|
|
279
|
-
**2.0.3** (October 17, 2011)
|
|
280
|
-
|
|
281
|
-
* Detect format extensions from right to left.
|
|
282
|
-
* Make JST namespace configurable.
|
|
283
|
-
|
|
284
|
-
**2.0.2** (October 4, 2011)
|
|
285
|
-
|
|
286
|
-
* Fixed loading stale cache from bundler gems.
|
|
287
|
-
|
|
288
|
-
**2.0.1** (September 30, 2011)
|
|
289
|
-
|
|
290
|
-
* Fixed bug with fingerprinting file names with multiple dots.
|
|
291
|
-
* Decode URIs as default internal.
|
|
292
|
-
* Fix symlinked asset directories.
|
|
293
|
-
|
|
294
|
-
**2.0.0** (August 29, 2011)
|
|
295
|
-
|
|
296
|
-
* Initial public release.
|
|
76
|
+
Please upgrade to the latest Sprockets 3 version before upgrading to Sprockets 4. Check the 3.x branch for previous changes https://github.com/rails/sprockets/blob/3.x/CHANGELOG.md.
|
data/README.md
CHANGED
|
@@ -5,7 +5,6 @@ It features declarative dependency management for JavaScript and CSS
|
|
|
5
5
|
assets, as well as a powerful preprocessor pipeline that allows you to
|
|
6
6
|
write assets in languages like CoffeeScript, Sass and SCSS.
|
|
7
7
|
|
|
8
|
-
|
|
9
8
|
## Installation
|
|
10
9
|
|
|
11
10
|
Install Sprockets from RubyGems:
|
|
@@ -17,493 +16,650 @@ $ gem install sprockets
|
|
|
17
16
|
Or include it in your project's `Gemfile` with Bundler:
|
|
18
17
|
|
|
19
18
|
``` ruby
|
|
20
|
-
gem 'sprockets', '~>
|
|
19
|
+
gem 'sprockets', '~> 4.0'
|
|
21
20
|
```
|
|
22
21
|
|
|
23
|
-
##
|
|
22
|
+
## Upgrading to Sprockets 4.x
|
|
24
23
|
|
|
25
|
-
|
|
24
|
+
These are the major features in Sprockets 4.x
|
|
26
25
|
|
|
27
|
-
|
|
26
|
+
- Source Maps
|
|
27
|
+
- Manifest.js
|
|
28
|
+
- ES6 support
|
|
29
|
+
- Deprecated processor interface in 3.x is removed in 4.x
|
|
28
30
|
|
|
29
|
-
|
|
31
|
+
Read more about them by referencing [Upgrading document](UPGRADING.md)
|
|
30
32
|
|
|
31
|
-
|
|
33
|
+
## Guides
|
|
32
34
|
|
|
33
|
-
|
|
35
|
+
For most people interested in using Sprockets, you will want to see the README below.
|
|
34
36
|
|
|
35
|
-
|
|
37
|
+
If you are a framework developer that is using Sprockets, see [Building an Asset Processing Framework](guides/building_an_asset_processing_framework.md).
|
|
36
38
|
|
|
37
|
-
|
|
39
|
+
If you are a library developer who is extending the functionality of Sprockets, see [Extending Sprockets](guides/extending_sprockets.md).
|
|
38
40
|
|
|
39
|
-
|
|
40
|
-
<%= asset_path("foo/index.js") %>
|
|
41
|
-
```
|
|
41
|
+
If you want to work on Sprockets or better understand how it works read [How Sprockets Works](guides/how_sprockets_works.md)
|
|
42
42
|
|
|
43
|
-
|
|
43
|
+
## Behavior Overview
|
|
44
44
|
|
|
45
|
-
|
|
46
|
-
<%= asset_path("foo.js") %>
|
|
47
|
-
```
|
|
45
|
+
You can interact with Sprockets primarily through directives and file extensions. This section covers how to use each of these things, and the defaults that ship with Sprockets.
|
|
48
46
|
|
|
49
|
-
|
|
47
|
+
Since you are likely using Sprockets through another framework (such as the [the Rails asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html)), there will be configuration options you can toggle that will change behavior such as what directories or files get compiled. For that documentation you should see your framework's documentation.
|
|
50
48
|
|
|
51
|
-
|
|
52
|
-
//= require_tree .
|
|
53
|
-
```
|
|
49
|
+
#### Accessing Assets
|
|
54
50
|
|
|
55
|
-
|
|
51
|
+
Assets in Sprockets are always referenced by their *logical path*.
|
|
56
52
|
|
|
57
|
-
|
|
53
|
+
The logical path is the path of the asset source file relative to its
|
|
54
|
+
containing directory in the load path. For example, if your load path
|
|
55
|
+
contains the directory `app/assets/javascripts`:
|
|
58
56
|
|
|
59
|
-
|
|
60
|
-
|
|
57
|
+
<table>
|
|
58
|
+
<tr>
|
|
59
|
+
<th>Logical path</th>
|
|
60
|
+
<th>Source file on disk</th>
|
|
61
|
+
</tr>
|
|
62
|
+
<tr>
|
|
63
|
+
<td>application.js</td>
|
|
64
|
+
<td>app/assets/javascripts/application.js</td>
|
|
65
|
+
</tr>
|
|
66
|
+
<tr>
|
|
67
|
+
<td>models/project.js</td>
|
|
68
|
+
<td>app/assets/javascripts/models/project.js</td>
|
|
69
|
+
</tr>
|
|
70
|
+
<tr>
|
|
71
|
+
<td>hello.js</td>
|
|
72
|
+
<td>app/assets/javascripts/hello.coffee</td>
|
|
73
|
+
</tr>
|
|
74
|
+
</table>
|
|
75
|
+
|
|
76
|
+
> Note: For assets that are compiled or transpiled, you want to specify the extension that you want, not the extension on disk. For example we specified `hello.js` even if the file on disk is a coffeescript file, since the asset it will generate is javascript.
|
|
77
|
+
|
|
78
|
+
### Directives
|
|
79
|
+
|
|
80
|
+
Directives are special comments in your asset file and the main way of interacting with processors. What kind of interactions? You can use these directives to tell Sprockets to load other files, or specify dependencies on other assets.
|
|
81
|
+
|
|
82
|
+
For example, let's say you have custom JavaScript that you've written. You put this javascript in a file called `beta.js`. The javascript makes heavy use of jQuery, so you need to load that before your code executes. You could add a `require` directive to the top of `beta.js`:
|
|
83
|
+
|
|
84
|
+
```js
|
|
85
|
+
//= require jquery
|
|
86
|
+
|
|
87
|
+
$().ready({
|
|
88
|
+
// my custom code here
|
|
89
|
+
})
|
|
61
90
|
```
|
|
62
91
|
|
|
63
|
-
|
|
92
|
+
The directive processor understands comment blocks in three formats:
|
|
64
93
|
|
|
94
|
+
``` css
|
|
95
|
+
/* Multi-line comment blocks (CSS, SCSS, JavaScript)
|
|
96
|
+
*= require foo
|
|
97
|
+
*/
|
|
65
98
|
```
|
|
66
|
-
|
|
67
|
-
|
|
99
|
+
|
|
100
|
+
``` js
|
|
101
|
+
// Single-line comment blocks (SCSS, JavaScript)
|
|
102
|
+
//= require foo
|
|
68
103
|
```
|
|
69
104
|
|
|
70
|
-
|
|
105
|
+
``` coffee
|
|
106
|
+
# Single-line comment blocks (CoffeeScript)
|
|
107
|
+
#= require foo
|
|
108
|
+
```
|
|
71
109
|
|
|
72
|
-
|
|
110
|
+
> Note: Directives are only processed if they come before any application code. Once you have a line that does not include a comment or whitespace then Sprockets will stop looking for directives. If you use a directive outside of the "header" of the document it will not do anything, and won't raise any errors.
|
|
73
111
|
|
|
74
|
-
|
|
75
|
-
access and serve assets from your application. Under Rails 4.0 and
|
|
76
|
-
later, `YourApp::Application.assets` is a preconfigured
|
|
77
|
-
`Sprockets::Environment` instance. For Rack-based applications, create
|
|
78
|
-
an instance in `config.ru`.
|
|
112
|
+
Here is a list of the available directives:
|
|
79
113
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
114
|
+
- [`require`](#require) - Add the contents of a file to current
|
|
115
|
+
- [`require_self`](#require_self) - Change order of where current contents are concatenated to current
|
|
116
|
+
- [`require_directory`](#require_directory) - Add contents of each file in a folder to current
|
|
117
|
+
- [`require_tree`](#require_tree) - Add contents of all files in all directories in a path to current
|
|
118
|
+
- [`link`](#link) - Make target file compile and be publicly available without adding contents to current
|
|
119
|
+
- [`link_directory`](#link_directory) - Make target directory compile and be publicly available without adding contents to current
|
|
120
|
+
- [`link_tree`](#link_tree) - Make target tree compile and be publicly available without adding contents to current
|
|
121
|
+
- [`depend_on`](#depend_on) - Recompile current file if target has changed
|
|
122
|
+
- [`stub`](#stub) - Ignore target file
|
|
84
123
|
|
|
85
|
-
|
|
124
|
+
You can see what each of these does below.
|
|
86
125
|
|
|
87
|
-
|
|
88
|
-
to search for assets.
|
|
126
|
+
### Specifying Processors through File Extensions
|
|
89
127
|
|
|
90
|
-
|
|
91
|
-
of a single directory containing your application's asset source
|
|
92
|
-
files. When mounted, the environment will serve assets from this
|
|
93
|
-
directory as if they were static files in your public root.
|
|
128
|
+
Sprockets uses the filename extensions to determine what processors to run on your file and in what order. For example if you have a file:
|
|
94
129
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
virtual filesystem. That means you can easily bundle JavaScript, CSS
|
|
99
|
-
and images into a Ruby library or [Bower](http://bower.io) package and import them into your application.
|
|
130
|
+
```
|
|
131
|
+
application.scss
|
|
132
|
+
```
|
|
100
133
|
|
|
101
|
-
|
|
134
|
+
Then Sprockets will by default run the sass processor (which implements scss). The output file will be converted to css.
|
|
102
135
|
|
|
103
|
-
|
|
104
|
-
`append_path` and `prepend_path` methods. Directories at the beginning
|
|
105
|
-
of the load path have precedence over subsequent directories.
|
|
136
|
+
You can specify multiple processors by specifying multiple file extensions. For example you can use Ruby's [ERB template language](#invoking-ruby-with-erb) to embed content in your doc before running the sass processor. To accomplish this you would need to name your file
|
|
106
137
|
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
environment.append_path 'app/assets/javascripts'
|
|
110
|
-
environment.append_path 'lib/assets/javascripts'
|
|
111
|
-
environment.append_path 'vendor/assets/bower_components'
|
|
138
|
+
```
|
|
139
|
+
application.scss.erb
|
|
112
140
|
```
|
|
113
141
|
|
|
114
|
-
|
|
115
|
-
prepending for cases where you need to override existing assets.
|
|
142
|
+
Processors are run from right to left (tail to head), so in the above example the processor associated with `erb` will be run before the processor associated with `scss` extension.
|
|
116
143
|
|
|
117
|
-
|
|
144
|
+
For a description of the processors that Sprockets has by default see the "default processors" section below. Other libraries may register additional processors.
|
|
118
145
|
|
|
119
|
-
|
|
120
|
-
environment as a Rack server and request assets via HTTP. You can also
|
|
121
|
-
access assets programmatically from within your application.
|
|
146
|
+
When "asking" for a compiled file, you always ask for the extension you want. For example if you're using Rails, to get the contents of `application.scss.erb` you would use
|
|
122
147
|
|
|
123
|
-
|
|
148
|
+
```
|
|
149
|
+
asset_path("application.css")
|
|
150
|
+
```
|
|
124
151
|
|
|
125
|
-
|
|
152
|
+
Sprockets understands that `application.scss.erb` will compile down to a `application.css`. Ask for what you need, not what you have.
|
|
126
153
|
|
|
127
|
-
|
|
128
|
-
containing directory in the load path. For example, if your load path
|
|
129
|
-
contains the directory `app/assets/javascripts`:
|
|
154
|
+
If this isn't working like you expect, make sure you didn't typo an extension, and make sure the file is on a "load path" (see framework docs for adding new load paths).
|
|
130
155
|
|
|
131
|
-
|
|
132
|
-
<tr>
|
|
133
|
-
<th>Asset source file</th>
|
|
134
|
-
<th>Logical path</th>
|
|
135
|
-
</tr>
|
|
136
|
-
<tr>
|
|
137
|
-
<td>app/assets/javascripts/application.js</td>
|
|
138
|
-
<td>application.js</td>
|
|
139
|
-
</tr>
|
|
140
|
-
<tr>
|
|
141
|
-
<td>app/assets/javascripts/models/project.js</td>
|
|
142
|
-
<td>models/project.js</td>
|
|
143
|
-
</tr>
|
|
144
|
-
</table>
|
|
156
|
+
## File Order Processing
|
|
145
157
|
|
|
146
|
-
|
|
147
|
-
virtual filesystem whose entries are logical paths.
|
|
158
|
+
By default files are processed in alphabetical order. This behavior can impact your asset compilation when one asset needs to be loaded before another.
|
|
148
159
|
|
|
149
|
-
|
|
160
|
+
For example if you have an `application.js` and it loads another directory
|
|
150
161
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
`/assets/application.js`, Sprockets will search your load path for the
|
|
155
|
-
file named `application.js` and serve it.
|
|
162
|
+
```js
|
|
163
|
+
//= require_directory my_javascript
|
|
164
|
+
```
|
|
156
165
|
|
|
157
|
-
|
|
158
|
-
mounted at `/assets`. If you are using Sprockets with a Rack
|
|
159
|
-
application, you will need to mount the environment yourself. A good
|
|
160
|
-
way to do this is with the `map` method in `config.ru`:
|
|
166
|
+
The files in that directory will be loaded in alphabetical order. If the directory looks like this:
|
|
161
167
|
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
168
|
+
```sh
|
|
169
|
+
$ ls -1 my_javascript/
|
|
170
|
+
|
|
171
|
+
alpha.js
|
|
172
|
+
beta.js
|
|
173
|
+
jquery.js
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Then `alpha.js` will be loaded before either of the other two. This can be a problem if `alpha.js` uses jquery. For this reason it is not recommend to use `require_directory` with files that are ordering dependent. You can either require individual files manually:
|
|
170
177
|
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
178
|
+
```js
|
|
179
|
+
//= require jquery
|
|
180
|
+
//= require alpha
|
|
181
|
+
//= require beta
|
|
174
182
|
```
|
|
175
183
|
|
|
176
|
-
|
|
184
|
+
Or you can use index files to proxy your folders.
|
|
177
185
|
|
|
178
|
-
|
|
179
|
-
asset from a Sprockets environment. Pass it a logical path and you'll
|
|
180
|
-
get a `Sprockets::Asset` instance back:
|
|
186
|
+
### Index files are proxies for folders
|
|
181
187
|
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
188
|
+
In Sprockets index files such as `index.js` or `index.css` files inside of a folder will generate a file with the folder's name. So if you have a `foo/index.js` file it will compile down to `foo.js`. This is similar to NPM's behavior of using [folders as modules](https://nodejs.org/api/modules.html#modules_folders_as_modules). It is also somewhat similar to the way that a file in `public/my_folder/index.html` can be reached by a request to `/my_folder`. This means that you cannot directly use an index file. For example this would not work:
|
|
189
|
+
|
|
190
|
+
```erb
|
|
191
|
+
<%= asset_path("foo/index.js") %>
|
|
185
192
|
```
|
|
186
193
|
|
|
187
|
-
|
|
188
|
-
get its length in bytes, `mtime` to query its last-modified time, and
|
|
189
|
-
`filename` to get its full path on the filesystem.
|
|
194
|
+
Instead you would need to use:
|
|
190
195
|
|
|
196
|
+
```erb
|
|
197
|
+
<%= asset_path("foo.js") %>
|
|
198
|
+
```
|
|
191
199
|
|
|
192
|
-
|
|
200
|
+
Why would you want to use this behavior? It is common behavior where you might want to include an entire directory of files in a top level JavaScript. You can do this in Sprockets using `require_tree .`
|
|
193
201
|
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
202
|
+
```js
|
|
203
|
+
//= require_tree .
|
|
204
|
+
```
|
|
197
205
|
|
|
198
|
-
|
|
206
|
+
This has the problem that files are required alphabetically. If your directory has `jquery-ui.js` and `jquery.min.js` then Sprockets will require `jquery-ui.js` before `jquery` is required which won't work (because jquery-ui depends on jquery). Previously the only way to get the correct ordering would be to rename your files, something like `0-jquery-ui.js`. Instead of doing that you can use an index file.
|
|
199
207
|
|
|
200
|
-
|
|
208
|
+
For example, if you have an `application.js` and want all the files in the `foo/` folder you could do this:
|
|
201
209
|
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
environment.css_compressor = :scss
|
|
210
|
+
```js
|
|
211
|
+
//= require foo.js
|
|
205
212
|
```
|
|
206
213
|
|
|
207
|
-
|
|
214
|
+
Then create a file `foo/index.js` that requires all the files in that folder in any order you want using relative references:
|
|
208
215
|
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
216
|
+
```js
|
|
217
|
+
//= require ./foo.min.js
|
|
218
|
+
//= require ./foo-ui.js
|
|
219
|
+
```
|
|
212
220
|
|
|
213
|
-
|
|
214
|
-
to write CSS assets in Sprockets.
|
|
221
|
+
Now in your `application.js` will correctly load the `foo.min.js` before `foo-ui.js`. If you used `require_tree` it would not work correctly.
|
|
215
222
|
|
|
216
|
-
|
|
217
|
-
whitespace-sensitive syntax, use the extension `.sass`. For the
|
|
218
|
-
new SCSS syntax, use the extension `.scss`.
|
|
223
|
+
## Cache
|
|
219
224
|
|
|
220
|
-
|
|
225
|
+
Compiling assets is slow. It requires a lot of disk use to pull assets off of hard drives, a lot of RAM to manipulate those files in memory, and a lot of CPU for compilation operations. Because of this Sprockets has a cache to speed up asset compilation times. That's the good news. The bad news, is that sprockets has a cache and if you've found a bug it's likely going to involve the cache.
|
|
221
226
|
|
|
222
|
-
|
|
223
|
-
language that compiles to the "good parts" of JavaScript, featuring a
|
|
224
|
-
cleaner syntax with array comprehensions, classes, and function
|
|
225
|
-
binding.
|
|
227
|
+
By default Sprockets uses the file system to cache assets. It makes sense that Sprockets does not want to generate assets that already exist on disk in `public/assets`, what might not be as intuitive is that Sprockets needs to cache "partial" assets.
|
|
226
228
|
|
|
227
|
-
|
|
228
|
-
use CoffeeScript to write JavaScript assets in Sprockets. Note that
|
|
229
|
-
the CoffeeScript compiler is written in JavaScript, and you will need
|
|
230
|
-
an [ExecJS](https://github.com/rails/execjs)-supported runtime
|
|
231
|
-
on your system to invoke it.
|
|
229
|
+
For example if you have an `application.js` and it is made up of `a.js`, `b.js`, all the way to `z.js`
|
|
232
230
|
|
|
233
|
-
|
|
234
|
-
|
|
231
|
+
```js
|
|
232
|
+
//= require a.js
|
|
233
|
+
//= require b.js
|
|
234
|
+
# ...
|
|
235
|
+
//= require z.js
|
|
236
|
+
```
|
|
235
237
|
|
|
236
|
-
|
|
238
|
+
The first time this file is compiled the `application.js` output will be written to disk, but also intermediary compiled files for `a.js` etc. will be written to the cache directory (usually `tmp/cache/assets`).
|
|
237
239
|
|
|
238
|
-
|
|
239
|
-
strings or markup. JavaScript templates have the special format
|
|
240
|
-
extension `.jst` and are compiled to JavaScript functions.
|
|
240
|
+
So, if `b.js` changes it will get recompiled. However instead of having to recompile the other files from `a.js` to `z.js` since they did not change, we can use the prior intermediary files stored in the cached values . If these files were expensive to generate, then this "partial" asset cache strategy can save a lot of time.
|
|
241
241
|
|
|
242
|
-
|
|
243
|
-
logical path as a property on the global `JST` object. Invoke a
|
|
244
|
-
template function to render the template as a string. The resulting
|
|
245
|
-
string can then be inserted into the DOM.
|
|
242
|
+
Directives such as `require`, `link`, and `depend_on` tell Sprockets what assets need to be re-compiled when a file changes. Files are considered "fresh" based on their mtime on disk and a combination of cache keys.
|
|
246
243
|
|
|
247
|
-
|
|
248
|
-
<!-- templates/hello.jst.ejs -->
|
|
249
|
-
<div>Hello, <span><%= name %></span>!</div>
|
|
244
|
+
On Rails you can force a "clean" install by clearing the `public/assets` and `tmp/cache/assets` directories.
|
|
250
245
|
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
246
|
+
|
|
247
|
+
## Default Directives
|
|
248
|
+
|
|
249
|
+
Directives take a path or a path to a file. Paths for directive can be relative to the current file, for example:
|
|
250
|
+
|
|
251
|
+
```js
|
|
252
|
+
//= require ../foo.js
|
|
254
253
|
```
|
|
255
254
|
|
|
256
|
-
|
|
257
|
-
[EJS](https://github.com/sstephenson/ruby-ejs), for embedded
|
|
258
|
-
JavaScript, and [Eco](https://github.com/sstephenson/ruby-eco), for
|
|
259
|
-
embedded CoffeeScript. Both languages use the familiar `<% … %>`
|
|
260
|
-
syntax for embedding logic in templates.
|
|
255
|
+
This would load the file up one directory and named `foo.js`. However this isn't required if `foo.js` is on one of Sprocket's load paths. You can simply use
|
|
261
256
|
|
|
262
|
-
|
|
263
|
-
|
|
257
|
+
```js
|
|
258
|
+
//= require foo.js
|
|
259
|
+
```
|
|
264
260
|
|
|
265
|
-
If the
|
|
266
|
-
templates](https://github.com/sstephenson/eco) in Sprockets. Eco
|
|
267
|
-
templates have the extension `.jst.eco`. Note that the `eco` gem
|
|
268
|
-
depends on the CoffeeScript compiler, so the same caveats apply as
|
|
269
|
-
outlined above for the CoffeeScript engine.
|
|
261
|
+
Without any prepended dots and sprockets will search for the asset. If the asset is on a sub-path of the load path, you can specify it without using a relative path as well:
|
|
270
262
|
|
|
271
|
-
|
|
263
|
+
```js
|
|
264
|
+
//= require sub/path/foo.js
|
|
265
|
+
```
|
|
272
266
|
|
|
273
|
-
|
|
274
|
-
embedded Ruby code. Append `.erb` to a CSS or JavaScript asset's
|
|
275
|
-
filename to enable the ERB engine.
|
|
267
|
+
You can also use an absolute path, but this is discouraged unless you know the directory structure of every machine you plan on running code on.
|
|
276
268
|
|
|
277
|
-
|
|
278
|
-
`Sprockets::Context` instance for the given asset. Common uses for ERB
|
|
279
|
-
include:
|
|
269
|
+
Below is a section for each of the built in directive types supported by Sprockets.
|
|
280
270
|
|
|
281
|
-
|
|
282
|
-
`asset_data_uri` helper
|
|
283
|
-
- inserting the URL to another asset, such as with the `asset_path`
|
|
284
|
-
helper provided by the Sprockets Rails plugin
|
|
285
|
-
- embedding other application resources, such as a localized string
|
|
286
|
-
database, in a JavaScript asset via JSON
|
|
287
|
-
- embedding version constants loaded from another file
|
|
271
|
+
### require
|
|
288
272
|
|
|
289
|
-
|
|
290
|
-
|
|
273
|
+
`require` *path* inserts the contents of the asset source file
|
|
274
|
+
specified by *path*. If the file is required multiple times, it will
|
|
275
|
+
appear in the bundle only once.
|
|
291
276
|
|
|
277
|
+
**Example:**
|
|
292
278
|
|
|
293
|
-
|
|
279
|
+
If you've got an `a.js`:
|
|
294
280
|
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
281
|
+
```js
|
|
282
|
+
var a = "A";
|
|
283
|
+
```
|
|
298
284
|
|
|
299
|
-
|
|
300
|
-
them to recursively build a dependency graph. When you request an
|
|
301
|
-
asset with dependencies, the dependencies will be included in order at
|
|
302
|
-
the top of the file.
|
|
285
|
+
and a `b.js`;
|
|
303
286
|
|
|
304
|
-
|
|
287
|
+
```js
|
|
288
|
+
var b = "B";
|
|
289
|
+
```
|
|
305
290
|
|
|
306
|
-
|
|
307
|
-
source file. The directive processor scans for comment lines beginning
|
|
308
|
-
with `=` in comment blocks at the top of the file.
|
|
291
|
+
Then you could require both of these in an `application.js`
|
|
309
292
|
|
|
310
|
-
```
|
|
311
|
-
//= require
|
|
312
|
-
//= require
|
|
313
|
-
//= require backbone
|
|
314
|
-
//= require_tree .
|
|
293
|
+
```js
|
|
294
|
+
//= require a.js
|
|
295
|
+
//= require b.js
|
|
315
296
|
```
|
|
316
297
|
|
|
317
|
-
|
|
318
|
-
name. Any words following the directive name are treated as
|
|
319
|
-
arguments. Arguments may be placed in single or double quotes if they
|
|
320
|
-
contain spaces, similar to commands in the Unix shell.
|
|
298
|
+
Which would generate one concatenated file:
|
|
321
299
|
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
300
|
+
```js
|
|
301
|
+
var a = "A";
|
|
302
|
+
var b = "B";
|
|
303
|
+
```
|
|
326
304
|
|
|
327
|
-
|
|
305
|
+
### require_self
|
|
328
306
|
|
|
329
|
-
|
|
307
|
+
`require_self` tells Sprockets to insert the body of the current
|
|
308
|
+
source file before any subsequent `require` directives.
|
|
330
309
|
|
|
331
|
-
|
|
332
|
-
/* Multi-line comment blocks (CSS, SCSS, JavaScript)
|
|
333
|
-
*= require foo
|
|
334
|
-
*/
|
|
335
|
-
```
|
|
310
|
+
**Example:**
|
|
336
311
|
|
|
337
|
-
|
|
338
|
-
// Single-line comment blocks (SCSS, JavaScript)
|
|
339
|
-
//= require foo
|
|
340
|
-
```
|
|
312
|
+
If you've got an `a.js`:
|
|
341
313
|
|
|
342
|
-
```
|
|
343
|
-
|
|
344
|
-
#= require foo
|
|
314
|
+
```js
|
|
315
|
+
var a = "A";
|
|
345
316
|
```
|
|
346
317
|
|
|
347
|
-
|
|
318
|
+
And an `application.js`
|
|
348
319
|
|
|
349
|
-
|
|
350
|
-
|
|
320
|
+
```js
|
|
321
|
+
//= require_self
|
|
322
|
+
//= require 'a.js'
|
|
351
323
|
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
reference files relative to the location of the current file.
|
|
324
|
+
var app_name = "Sprockets";
|
|
325
|
+
```
|
|
355
326
|
|
|
356
|
-
|
|
327
|
+
Then this will take the contents of `application.js` (that come after the last require) and put them at the beginning of the file:
|
|
357
328
|
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
329
|
+
```js
|
|
330
|
+
var app_name = "Sprockets";
|
|
331
|
+
var a = "A";
|
|
332
|
+
```
|
|
361
333
|
|
|
362
|
-
###
|
|
334
|
+
### require_directory
|
|
363
335
|
|
|
364
336
|
`require_directory` *path* requires all source files of the same
|
|
365
337
|
format in the directory specified by *path*. Files are required in
|
|
366
338
|
alphabetical order.
|
|
367
339
|
|
|
368
|
-
|
|
340
|
+
**Example:**
|
|
341
|
+
|
|
342
|
+
If we've got a directory called `alphabet` with an `a.js` and `b.js` files like before, then our `application.js`
|
|
343
|
+
|
|
344
|
+
```js
|
|
345
|
+
//= require_directory alphabet
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
Would produce:
|
|
349
|
+
|
|
350
|
+
```js
|
|
351
|
+
var a = "A";
|
|
352
|
+
var b = "B";
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
You can also see [Index files are proxies for folders](#index-files-are-proxies-for-folders) for another method of organizing folders that will give you more control.
|
|
356
|
+
|
|
357
|
+
### require_tree
|
|
369
358
|
|
|
370
359
|
`require_tree` *path* works like `require_directory`, but operates
|
|
371
360
|
recursively to require all files in all subdirectories of the
|
|
372
361
|
directory specified by *path*.
|
|
373
362
|
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
`require_self` tells Sprockets to insert the body of the current
|
|
377
|
-
source file before any subsequent `require` directives.
|
|
378
|
-
|
|
379
|
-
#### The `link` Directive
|
|
363
|
+
### link
|
|
380
364
|
|
|
381
365
|
`link` *path* declares a dependency on the target *path* and adds it to a list
|
|
382
|
-
of subdependencies to
|
|
366
|
+
of subdependencies to be compiled when the asset is written out to
|
|
383
367
|
disk.
|
|
384
368
|
|
|
385
|
-
|
|
386
|
-
needs to be compiled along with the css file.
|
|
369
|
+
Example:
|
|
387
370
|
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
371
|
+
If you've got a `manifest.js` file and you want to specify that a `admin.js` source file should be
|
|
372
|
+
generated and made available to the public you can link it by including this in the `manifest.js` file:
|
|
373
|
+
|
|
374
|
+
```
|
|
375
|
+
//= link admin.js
|
|
393
376
|
```
|
|
394
377
|
|
|
395
|
-
|
|
396
|
-
|
|
378
|
+
The argument to `link` is a _logical path_, that is it will be resolved according to the
|
|
379
|
+
configured asset load paths. See [Accesing Assets](#accessing-assets) above. A path relative to
|
|
380
|
+
the current file won't work, it must be a logical path.
|
|
397
381
|
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
382
|
+
**Caution**: the "link" directive should always have an explicit extension on the end.
|
|
383
|
+
|
|
384
|
+
### link_directory
|
|
385
|
+
|
|
386
|
+
`link_directory` *path* links all the files inside the directory specified by the *path*. By "link", we mean they are specified as compilation targets to be written out to disk, and made available to be served to user-agents.
|
|
387
|
+
|
|
388
|
+
Files in subdirectories will not be linked (Compare to [link_tree](#link_tree)).
|
|
389
|
+
|
|
390
|
+
The *path* argument to `link_directory` is _not_ a logical path (it does not use the asset load paths), but is a path relative to the file the `link_directory` directive is found in, and can use `..` to . For instance, you might want:
|
|
391
|
+
|
|
392
|
+
```js
|
|
393
|
+
//= link_directory ../stylesheets
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
`link_directory` can take an optional second argument with an extension or content-type, with the
|
|
397
|
+
two arguments separated by a space:
|
|
398
|
+
|
|
399
|
+
```js
|
|
400
|
+
//= link_directory ../stylesheets text/css
|
|
401
|
+
//= link_directory ../more_stylesheets .css
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
This will limit the matching files to link to only files recognized as that type. An extension is
|
|
405
|
+
just a shortcut for the type referenced, it does not need to match the source file exactly, but
|
|
406
|
+
instead identifies the content-type the source file must be recognized as.
|
|
407
|
+
|
|
408
|
+
### link_tree
|
|
409
|
+
|
|
410
|
+
`link_tree` *path* works like [link_directory](#link_directory), but operates
|
|
411
|
+
recursively to link all files in all subdirectories of the
|
|
412
|
+
directory specified by *path*.
|
|
413
|
+
|
|
414
|
+
Example:
|
|
415
|
+
|
|
416
|
+
```js
|
|
417
|
+
//= link_tree ./path/to/folder
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
Like `link_directory`, the argument is path relative to the current file, it is *not* a 'logical path' tresolved against load paths.
|
|
421
|
+
|
|
422
|
+
|
|
423
|
+
As with `link_directory`, you can also specify a second argument -- separated by a space -- so any extra files not matching the content-type specified will be ignored:
|
|
424
|
+
|
|
425
|
+
```js
|
|
426
|
+
//= link_tree ./path/to/folder text/javascript
|
|
427
|
+
//= link_tree ./path/to/other_folder .js
|
|
402
428
|
```
|
|
403
429
|
|
|
404
|
-
|
|
430
|
+
|
|
431
|
+
### depend_on
|
|
405
432
|
|
|
406
433
|
`depend_on` *path* declares a dependency on the given *path* without
|
|
407
434
|
including it in the bundle. This is useful when you need to expire an
|
|
408
435
|
asset's cache in response to a change in another file.
|
|
409
436
|
|
|
410
|
-
|
|
437
|
+
**Example:**
|
|
438
|
+
|
|
439
|
+
If you have a file such as `bar.data` and you're using data from that file in another file, then
|
|
440
|
+
you need to tell sprockets that it needs to re-compile the file if `bar.data` changes:
|
|
441
|
+
|
|
442
|
+
```js
|
|
443
|
+
//= depend_on "bar.data"
|
|
444
|
+
|
|
445
|
+
var bar = '<%= File.read("bar.data") %>'
|
|
446
|
+
```
|
|
447
|
+
|
|
448
|
+
### depend_on_asset
|
|
411
449
|
|
|
412
450
|
`depend_on_asset` *path* works like `depend_on`, but operates
|
|
413
451
|
recursively reading the file and following the directives found. This is automatically implied if you use `link`, so consider if it just makes sense using `link` instead of `depend_on_asset`.
|
|
414
452
|
|
|
415
|
-
|
|
453
|
+
### stub
|
|
416
454
|
|
|
417
|
-
`stub` *path*
|
|
455
|
+
`stub` *path* excludes that asset and its dependencies from the asset bundle.
|
|
418
456
|
The *path* must be a valid asset and may or may not already be part
|
|
419
457
|
of the bundle. `stub` should only be used at the top level bundle, not
|
|
420
458
|
within any subdependencies.
|
|
421
459
|
|
|
460
|
+
### Invoking Ruby with ERB
|
|
422
461
|
|
|
423
|
-
|
|
462
|
+
Sprockets provides an ERB engine for preprocessing assets using
|
|
463
|
+
embedded Ruby code. Append `.erb` to a CSS or JavaScript asset's
|
|
464
|
+
filename to enable the ERB engine.
|
|
424
465
|
|
|
425
|
-
|
|
466
|
+
For example if you have an `app/application/javascripts/app_name.js.erb`
|
|
467
|
+
you could have this in the template
|
|
426
468
|
|
|
427
|
-
|
|
469
|
+
```js
|
|
470
|
+
var app_name = "<%= ENV['APP_NAME'] %>";
|
|
471
|
+
```
|
|
428
472
|
|
|
429
|
-
|
|
473
|
+
Generated files are cached. If you're using an `ENV` var then
|
|
474
|
+
when you change then ENV var the asset will be forced to
|
|
475
|
+
recompile. This behavior is only true for environment variables,
|
|
476
|
+
if you are pulling a value from somewhere else, such as a database,
|
|
477
|
+
must manually invalidate the cache to see the change.
|
|
430
478
|
|
|
431
|
-
|
|
479
|
+
If you're using Rails, there are helpers you can use such as `asset_url`
|
|
480
|
+
that will cause a recompile if the value changes.
|
|
432
481
|
|
|
433
|
-
|
|
482
|
+
For example if you have this in your `application.css`
|
|
434
483
|
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
484
|
+
``` css
|
|
485
|
+
.logo {
|
|
486
|
+
background: url(<%= asset_url("logo.png") %>)
|
|
487
|
+
}
|
|
488
|
+
```
|
|
489
|
+
|
|
490
|
+
When you modify the `logo.png` on disk, it will force `application.css` to be
|
|
491
|
+
recompiled so that the fingerprint will be correct in the generated asset.
|
|
492
|
+
|
|
493
|
+
You can manually make sprockets depend on any other file that is generated
|
|
494
|
+
by sprockets by using the `depend_on` directive. Rails implements the above
|
|
495
|
+
feature by auto calling `depend_on` on the original asset when the `asset_url`
|
|
496
|
+
is used inside of an asset.
|
|
497
|
+
|
|
498
|
+
### Styling with Sass and SCSS
|
|
499
|
+
|
|
500
|
+
[Sass](http://sass-lang.com/) is a language that compiles to CSS and
|
|
501
|
+
adds features like nested rules, variables, mixins and selector
|
|
502
|
+
inheritance.
|
|
503
|
+
|
|
504
|
+
If the `sass` gem is available to your application, you can use Sass
|
|
505
|
+
to write CSS assets in Sprockets.
|
|
506
|
+
|
|
507
|
+
Sprockets supports both Sass syntaxes. For the original
|
|
508
|
+
whitespace-sensitive syntax, use the extension `.sass`. For the
|
|
509
|
+
new SCSS syntax, use the extension `.scss`.
|
|
510
|
+
|
|
511
|
+
In Rails if you have `app/application/stylesheets/foo.scss` it can
|
|
512
|
+
be referenced with `<%= asset_path("foo.css") %>`. When referencing
|
|
513
|
+
an asset in Rails, always specify the extension you want. Sprockets will
|
|
514
|
+
convert `foo.scss` to `foo.css`.
|
|
515
|
+
|
|
516
|
+
### Scripting with CoffeeScript
|
|
517
|
+
|
|
518
|
+
[CoffeeScript](http://jashkenas.github.io/coffeescript/) is a
|
|
519
|
+
language that compiles to the "good parts" of JavaScript, featuring a
|
|
520
|
+
cleaner syntax with array comprehensions, classes, and function
|
|
521
|
+
binding.
|
|
522
|
+
|
|
523
|
+
If the `coffee-script` gem is available to your application, you can
|
|
524
|
+
use CoffeeScript to write JavaScript assets in Sprockets. Note that
|
|
525
|
+
the CoffeeScript compiler is written in JavaScript, and you will need
|
|
526
|
+
an [ExecJS](https://github.com/rails/execjs)-supported runtime
|
|
527
|
+
on your system to invoke it.
|
|
528
|
+
|
|
529
|
+
To write JavaScript assets with CoffeeScript, use the extension
|
|
530
|
+
`.coffee`.
|
|
531
|
+
|
|
532
|
+
In Rails if you have `app/application/javascripts/foo.coffee` it can
|
|
533
|
+
be referenced with `<%= asset_path("foo.js") %>`. When referencing
|
|
534
|
+
an asset in Rails, always specify the extension you want. Sprockets will
|
|
535
|
+
convert `foo.coffee` to `foo.js`.
|
|
536
|
+
|
|
537
|
+
|
|
538
|
+
## ES6 Support
|
|
539
|
+
|
|
540
|
+
Sprockets 4 ships with a Babel processor. This allows you to transpile ECMAScript6 to JavaScript just like you would transpile CoffeeScript to JavaScript. To use this, modify your Gemfile:
|
|
541
|
+
|
|
542
|
+
```ruby
|
|
543
|
+
gem 'babel-transpiler'
|
|
544
|
+
```
|
|
545
|
+
|
|
546
|
+
Any asset with the extension `es6` will be treated as an ES6 file:
|
|
547
|
+
|
|
548
|
+
```es6
|
|
549
|
+
// app/assets/javascript/application.es6
|
|
550
|
+
|
|
551
|
+
var square = (n) => n * n
|
|
552
|
+
|
|
553
|
+
console.log(square);
|
|
554
|
+
```
|
|
555
|
+
|
|
556
|
+
Start a Rails server in development mode and visit `localhost:3000/assets/application.js`, and this asset will be transpiled to JavaScript:
|
|
557
|
+
|
|
558
|
+
```js
|
|
559
|
+
var square = function square(n) {
|
|
560
|
+
return n * n;
|
|
561
|
+
};
|
|
562
|
+
|
|
563
|
+
console.log(square);
|
|
564
|
+
```
|
|
565
|
+
|
|
566
|
+
|
|
567
|
+
### JavaScript Templating with EJS and Eco
|
|
568
|
+
|
|
569
|
+
Sprockets supports *JavaScript templates* for client-side rendering of
|
|
570
|
+
strings or markup. JavaScript templates have the special format
|
|
571
|
+
extension `.jst` and are compiled to JavaScript functions.
|
|
572
|
+
|
|
573
|
+
When loaded, a JavaScript template function can be accessed by its
|
|
574
|
+
logical path as a property on the global `JST` object. Invoke a
|
|
575
|
+
template function to render the template as a string. The resulting
|
|
576
|
+
string can then be inserted into the DOM.
|
|
444
577
|
|
|
445
|
-
``` ruby
|
|
446
|
-
def self.call(input)
|
|
447
|
-
input[:cache].fetch("my:cache:key:v1") do
|
|
448
|
-
# Remove all semicolons from source
|
|
449
|
-
input[:data].gsub(";", "")
|
|
450
|
-
end
|
|
451
|
-
end
|
|
452
578
|
```
|
|
579
|
+
<!-- templates/hello.jst.ejs -->
|
|
580
|
+
<div>Hello, <span><%= name %></span>!</div>
|
|
453
581
|
|
|
454
|
-
|
|
582
|
+
// application.js
|
|
583
|
+
//= require templates/hello
|
|
584
|
+
$("#hello").html(JST["templates/hello"]({ name: "Sam" }));
|
|
585
|
+
```
|
|
586
|
+
|
|
587
|
+
Sprockets supports two JavaScript template languages:
|
|
588
|
+
[EJS](https://github.com/sstephenson/ruby-ejs), for embedded
|
|
589
|
+
JavaScript, and [Eco](https://github.com/sstephenson/ruby-eco), for
|
|
590
|
+
embedded CoffeeScript. Both languages use the familiar `<% … %>`
|
|
591
|
+
syntax for embedding logic in templates.
|
|
455
592
|
|
|
456
|
-
|
|
593
|
+
If the `ejs` gem is available to your application, you can use EJS
|
|
594
|
+
templates in Sprockets. EJS templates have the extension `.jst.ejs`.
|
|
457
595
|
|
|
458
|
-
|
|
596
|
+
If the `eco` gem is available to your application, you can use [Eco
|
|
597
|
+
templates](https://github.com/sstephenson/eco) in Sprockets. Eco
|
|
598
|
+
templates have the extension `.jst.eco`. Note that the `eco` gem
|
|
599
|
+
depends on the CoffeeScript compiler, so the same caveats apply as
|
|
600
|
+
outlined above for the CoffeeScript engine.
|
|
459
601
|
|
|
460
|
-
###
|
|
602
|
+
### Minifying Assets
|
|
461
603
|
|
|
462
|
-
|
|
604
|
+
Several JavaScript and CSS minifiers are available through shorthand.
|
|
463
605
|
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
606
|
+
In Rails you will specify them with:
|
|
607
|
+
|
|
608
|
+
```ruby
|
|
609
|
+
config.assets.js_compressor = :uglify
|
|
610
|
+
config.assets.css_compressor = :scss
|
|
611
|
+
```
|
|
612
|
+
|
|
613
|
+
If you're not using Rails, configure this directly on the "environment".
|
|
468
614
|
|
|
469
615
|
``` ruby
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
616
|
+
environment.js_compressor = :uglify
|
|
617
|
+
environment.css_compressor = :scss
|
|
618
|
+
```
|
|
473
619
|
|
|
474
|
-
|
|
475
|
-
|
|
620
|
+
If you are using Sprockets directly with a Rack app, don't forget to add
|
|
621
|
+
the `uglifier` and `sass` gems to your Gemfile when using above options.
|
|
622
|
+
|
|
623
|
+
### Gzip
|
|
624
|
+
|
|
625
|
+
By default when Sprockets generates a compiled asset file it will also produce a gzipped copy of that file. Sprockets only gzips non-binary files such as CSS, javascript, and SVG files.
|
|
626
|
+
|
|
627
|
+
For example if Sprockets is generating
|
|
476
628
|
|
|
477
|
-
|
|
478
|
-
|
|
629
|
+
```
|
|
630
|
+
application-12345.css
|
|
479
631
|
```
|
|
480
632
|
|
|
633
|
+
Then it will also generate a compressed copy in
|
|
481
634
|
|
|
482
|
-
|
|
635
|
+
```
|
|
636
|
+
application-12345.css.gz
|
|
637
|
+
```
|
|
483
638
|
|
|
484
|
-
|
|
639
|
+
This behavior can be disabled, refer to your framework specific documentation.
|
|
485
640
|
|
|
486
|
-
|
|
487
|
-
GitHub](https://github.com/rails/sprockets). You can check out a
|
|
488
|
-
copy of the latest code using Git:
|
|
641
|
+
### Serving Assets
|
|
489
642
|
|
|
490
|
-
|
|
643
|
+
In production you should generate your assets to a directory on disk and serve them either via Nginx or a feature like Rail's `config.public_file_server.enabled = true`.
|
|
491
644
|
|
|
492
|
-
|
|
493
|
-
[Sprockets issue
|
|
494
|
-
tracker](https://github.com/rails/sprockets/issues). Or, clone
|
|
495
|
-
the Sprockets repository, write a failing test case, fix the bug and
|
|
496
|
-
submit a pull request.
|
|
645
|
+
On Rails you can generate assets by running:
|
|
497
646
|
|
|
498
|
-
|
|
647
|
+
```term
|
|
648
|
+
$ RAILS_ENV=production rake assets:precompile
|
|
649
|
+
```
|
|
499
650
|
|
|
500
|
-
|
|
651
|
+
In development Rails will serve assets from `Sprockets::Server`.
|
|
501
652
|
|
|
502
|
-
##
|
|
653
|
+
## Contributing to Sprockets
|
|
503
654
|
|
|
504
|
-
|
|
655
|
+
Sprockets is the work of hundreds of contributors. You're encouraged to submit pull requests, propose
|
|
656
|
+
features and discuss issues.
|
|
505
657
|
|
|
506
|
-
|
|
658
|
+
See [CONTRIBUTING](CONTRIBUTING.md).
|
|
507
659
|
|
|
508
|
-
|
|
509
|
-
|
|
660
|
+
### Version History
|
|
661
|
+
|
|
662
|
+
Please see the [CHANGELOG](https://github.com/rails/sprockets/tree/master/CHANGELOG.md)
|
|
663
|
+
|
|
664
|
+
## License
|
|
665
|
+
Sprockets is released under the [MIT License](MIT-LICENSE).
|