condenser 0.0.7 → 0.0.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/LICENSE +1 -1
- data/README.md +283 -1
- data/lib/condenser/manifest.rb +4 -1
- data/lib/condenser/version.rb +1 -1
- data/lib/condenser/writers/file_writer.rb +5 -1
- data/lib/condenser/writers/zlib_writer.rb +5 -1
- metadata +2 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: ab40d1eb05ff854d115ac6c4118dc6c8f963f96a71f52d9f0ef326eea9867d66
|
4
|
+
data.tar.gz: 3f0fe2328e3b53f3e42d6c248267f16e631602ad0e67e8b669af08690f4df208
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: a5f165dc1e99735799efca86ba2ceb76660750ed92a1dfb4143e39654b472b5f1664a49fe1b6967b687e54e3c06209de3a075ac882e2bb1e0a231361f8de13b4
|
7
|
+
data.tar.gz: bf13599783b114ef0f520f48cc613a3ec4ace5174e6867f3c01ae79c50044455a8354d498dd90800effe561c479e89661a80701deefeddd69721376af04f5c47
|
data/LICENSE
CHANGED
data/README.md
CHANGED
@@ -1 +1,283 @@
|
|
1
|
-
|
1
|
+
|
2
|
+
# Condenser
|
3
|
+
|
4
|
+
Condenser is a Ruby library for compiling and serving static web assets
|
5
|
+
inspired by [Sprockets](https://github.com/rails/sprockets). It features
|
6
|
+
a powerful pipeline that allows you to write assets in languages like Sass
|
7
|
+
and SCSS.
|
8
|
+
|
9
|
+
## Installation
|
10
|
+
|
11
|
+
Install Sprockets from RubyGems:
|
12
|
+
|
13
|
+
``` sh
|
14
|
+
$ gem install condenser
|
15
|
+
```
|
16
|
+
|
17
|
+
Or include it in your project's `Gemfile` with Bundler:
|
18
|
+
|
19
|
+
``` ruby
|
20
|
+
gem 'condenser'
|
21
|
+
```
|
22
|
+
|
23
|
+
## Guides
|
24
|
+
|
25
|
+
For most people interested in Condenser, you will want to see the README below.
|
26
|
+
|
27
|
+
If you are a framework developer see [Building an Asset Processing Framework](guides/building_an_asset_processing_framework.md).
|
28
|
+
|
29
|
+
If you are a library developer who is extending Condenser, see [Extending Condenser](guides/extending_condenser.md).
|
30
|
+
|
31
|
+
If you want to work on Condenser or better understand how it works read [How Condenser Works](guides/how_condenser_works.md).
|
32
|
+
|
33
|
+
## Overview
|
34
|
+
|
35
|
+
Since you are likely using Condenser through another framework, there will be
|
36
|
+
configuration options you can toggle that will change behavior such as what
|
37
|
+
directories or files get compiled. For that documentation you should see your
|
38
|
+
framework's documentation.
|
39
|
+
|
40
|
+
#### Accessing Assets
|
41
|
+
|
42
|
+
Assets in Condenser are always referenced by their *logical path*.
|
43
|
+
|
44
|
+
The logical path is the path of the asset source file relative to its
|
45
|
+
containing directory in the load path. For example, if your load path
|
46
|
+
contains the directory `app/assets/javascripts`:
|
47
|
+
|
48
|
+
<table>
|
49
|
+
<tr>
|
50
|
+
<th>Logical path</th>
|
51
|
+
<th>Source file on disk</th>
|
52
|
+
</tr>
|
53
|
+
<tr>
|
54
|
+
<td>application.js</td>
|
55
|
+
<td>app/assets/javascripts/application.js</td>
|
56
|
+
</tr>
|
57
|
+
<tr>
|
58
|
+
<td>models/project.js</td>
|
59
|
+
<td>app/assets/javascripts/models/project.js</td>
|
60
|
+
</tr>
|
61
|
+
<tr>
|
62
|
+
<td>hello.js</td>
|
63
|
+
<td>app/assets/javascripts/hello.coffee</td>
|
64
|
+
</tr>
|
65
|
+
</table>
|
66
|
+
|
67
|
+
> Note: For assets that are compiled or transpiled, you may want to specify the
|
68
|
+
extension that you want, not the extension on disk. For example we specified
|
69
|
+
`hello.js` even if the file on disk is a coffeescript file, since the asset
|
70
|
+
it will generate is javascript.
|
71
|
+
|
72
|
+
## File Order Processing
|
73
|
+
|
74
|
+
By default files are processed in alphabetical order. This behavior can impact your asset compilation when one asset needs to be loaded before another.
|
75
|
+
|
76
|
+
For example if you have an `application.js` and it loads another directory
|
77
|
+
|
78
|
+
```js
|
79
|
+
import initializers from 'config/initializers/*';
|
80
|
+
|
81
|
+
initializers.forEach((i) => i());
|
82
|
+
```
|
83
|
+
|
84
|
+
The files in that directory will be loaded in alphabetical order. If the directory looks like this:
|
85
|
+
|
86
|
+
```sh
|
87
|
+
$ ls -1 config/initializers/
|
88
|
+
|
89
|
+
alpha.js
|
90
|
+
beta.js
|
91
|
+
gamma.js
|
92
|
+
```
|
93
|
+
|
94
|
+
Then `alpha.js` will be loaded before either of the other two. This can be a problem if `gamma.js` needs to be called before `alpha.js`. For files that are ordering dependent you can either require individual files manually:
|
95
|
+
|
96
|
+
```js
|
97
|
+
import alpha from 'config/initializers/alpha';
|
98
|
+
import beta from 'config/initializers/beta';
|
99
|
+
import gamma from 'config/initializers/gamma';
|
100
|
+
|
101
|
+
gamma();
|
102
|
+
alpha();
|
103
|
+
beta();
|
104
|
+
```
|
105
|
+
|
106
|
+
## Cache
|
107
|
+
|
108
|
+
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 Condenser has a cache to speed up asset compilation times. That's the good news. The bad news, is that Condenser has a cache and if you've found a bug it's likely going to involve the cache.
|
109
|
+
|
110
|
+
By default Condenser uses the file system to cache assets. It makes sense that Condenser does not want to generate assets that already exist on disk in `public/assets`, what might not be as intuitive is that Condenser needs to cache "partial" assets.
|
111
|
+
|
112
|
+
For example if you have an `application.js` and it is made up of `a.js`, `b.js`, all the way to `z.js`
|
113
|
+
|
114
|
+
```js
|
115
|
+
import 'a';
|
116
|
+
import 'b';
|
117
|
+
// ...
|
118
|
+
import 'z';
|
119
|
+
```
|
120
|
+
|
121
|
+
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`).
|
122
|
+
|
123
|
+
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.
|
124
|
+
|
125
|
+
Directives such as `import` in Javascript and `@import` in SCSS tell Condenser what assets need to be re-compiled when a file changes. Files are considered "fresh" based on their inode number, mtime, size and a combination of cache keys.
|
126
|
+
|
127
|
+
In Rails you can force a "clean" install by clearing the `public/assets` and `tmp/cache/assets` directories.
|
128
|
+
|
129
|
+
### Invoking Ruby with ERB
|
130
|
+
|
131
|
+
Condenser provides an ERB engine for preprocessing assets using
|
132
|
+
embedded Ruby code. Append `.erb` to a CSS or JavaScript asset's
|
133
|
+
filename to enable the ERB engine.
|
134
|
+
|
135
|
+
For example if you have an `app/application/javascripts/app_name.js.erb`
|
136
|
+
you could have this in the template
|
137
|
+
|
138
|
+
```js
|
139
|
+
var app_name = "<%= ENV['APP_NAME'] %>";
|
140
|
+
```
|
141
|
+
|
142
|
+
Generated files are cached. If you're using an `ENV` var then
|
143
|
+
when you change then ENV var the asset will be forced to
|
144
|
+
recompile. This behavior is only true for environment variables,
|
145
|
+
if you are pulling a value from somewhere else, such as a database,
|
146
|
+
must manually invalidate the cache to see the change.
|
147
|
+
|
148
|
+
If you're using Rails, there are helpers you can use such as `asset_url`
|
149
|
+
that will cause a recompile if the value changes.
|
150
|
+
|
151
|
+
For example if you have this in your `application.css.erb`
|
152
|
+
|
153
|
+
``` css.erb
|
154
|
+
.logo {
|
155
|
+
background: url(<%= asset_url("logo.png") %>)
|
156
|
+
}
|
157
|
+
```
|
158
|
+
|
159
|
+
When you modify the `logo.png` on disk, it will force `application.css` to be
|
160
|
+
recompiled so that the fingerprint will be correct in the generated asset.
|
161
|
+
|
162
|
+
### Styling with Sass and SCSS
|
163
|
+
|
164
|
+
[Sass](http://sass-lang.com/) is a language that compiles to CSS and
|
165
|
+
adds features like nested rules, variables, mixins and selector
|
166
|
+
inheritance.
|
167
|
+
|
168
|
+
If the `sassc` gem is available to your application, you can use Sass
|
169
|
+
to write CSS assets in Condenser.
|
170
|
+
|
171
|
+
Condenser supports both Sass syntaxes. For the original
|
172
|
+
whitespace-sensitive syntax, use the extension `.sass`. For the
|
173
|
+
new SCSS syntax, use the extension `.scss`.
|
174
|
+
|
175
|
+
In Rails if you have `app/application/stylesheets/foo.scss` it can
|
176
|
+
be referenced with `<%= asset_path("foo.css") %>`. When referencing
|
177
|
+
an asset in Rails, always specify the extension you want. Condenser will
|
178
|
+
convert `foo.scss` to `foo.css`.
|
179
|
+
|
180
|
+
## Javascript, ES#, & ES Modules
|
181
|
+
|
182
|
+
Condenser transforms Javascript for the browser by transpiling all the files `.js` through [babel](https://babeljs.io) and bundled together via [rollup.js](https://rollupjs.org/).
|
183
|
+
|
184
|
+
```js
|
185
|
+
// app/assets/javascript/application.js
|
186
|
+
|
187
|
+
var square = (n) => n * n
|
188
|
+
|
189
|
+
console.log(square);
|
190
|
+
```
|
191
|
+
|
192
|
+
Start a Rails server in development mode and visit `localhost:3000/assets/application.js`, and this asset will be transpiled to JavaScript:
|
193
|
+
|
194
|
+
```js
|
195
|
+
var square = function square(n) {
|
196
|
+
return n * n;
|
197
|
+
};
|
198
|
+
|
199
|
+
console.log(square);
|
200
|
+
```
|
201
|
+
|
202
|
+
|
203
|
+
### JavaScript Templating with EJS
|
204
|
+
|
205
|
+
Condenser supports *JavaScript templates* for client-side rendering of
|
206
|
+
strings or markup. JavaScript templates have the special format
|
207
|
+
extension `.jst` and are compiled to JavaScript functions.
|
208
|
+
|
209
|
+
The templates can then be imported. When invoked they will render the template
|
210
|
+
as a string that can be inserted into the DOM.
|
211
|
+
|
212
|
+
```javascript
|
213
|
+
<!-- templates/hello.jst.ejs -->
|
214
|
+
<div>Hello, <span><%= name %></span>!</div>
|
215
|
+
|
216
|
+
import hello from 'templates/hello';
|
217
|
+
|
218
|
+
$("#hello").html(hello({ name: "Sam" }));
|
219
|
+
```
|
220
|
+
|
221
|
+
If the `ejs` gem is available to your application, you can use EJS
|
222
|
+
templates in Condenser. EJS templates have the extension `.jst.ejs`.
|
223
|
+
|
224
|
+
### Minifying Assets
|
225
|
+
|
226
|
+
Several JavaScript and CSS minifiers are available through shorthand.
|
227
|
+
|
228
|
+
In Rails you will specify them with:
|
229
|
+
|
230
|
+
```ruby
|
231
|
+
config.assets.js_minifier = :uglify
|
232
|
+
config.assets.css_minifier = :scss
|
233
|
+
```
|
234
|
+
|
235
|
+
If you're not using Rails, configure this directly on the "environment".
|
236
|
+
|
237
|
+
``` ruby
|
238
|
+
environment.register_minifier 'text/css', Condenser::SassMinifier
|
239
|
+
environment.register_minifier 'application/javascript', Condenser::UglifyMinifier
|
240
|
+
```
|
241
|
+
|
242
|
+
If you are using Condenser directly with a Rack app, don't forget to add
|
243
|
+
the dependencies (the `sassc` gem in the example above) to your Gemfile.
|
244
|
+
|
245
|
+
### Gzip
|
246
|
+
|
247
|
+
By default when Condenser generates a compiled asset file it will also produce a
|
248
|
+
gzipped copy of that file. Condenser only gzips non-binary files such as CSS,
|
249
|
+
javascript, and SVG files.
|
250
|
+
|
251
|
+
For example if Condenser is generating
|
252
|
+
|
253
|
+
```
|
254
|
+
application-12345.css
|
255
|
+
```
|
256
|
+
|
257
|
+
Then it will also generate a compressed copy in
|
258
|
+
|
259
|
+
```
|
260
|
+
application-12345.css.gz
|
261
|
+
```
|
262
|
+
|
263
|
+
This behavior can be disabled, refer to your framework specific documentation.
|
264
|
+
|
265
|
+
### Serving Assets
|
266
|
+
|
267
|
+
In production you should generate your assets to a directory on disk and serve
|
268
|
+
them either via Nginx or a feature like Rail's `config.public_file_server.enabled = true`.
|
269
|
+
|
270
|
+
On Rails you can generate assets by running:
|
271
|
+
|
272
|
+
```term
|
273
|
+
$ RAILS_ENV=production rails assets:precompile
|
274
|
+
```
|
275
|
+
|
276
|
+
In development Rails will serve assets from `Condenser::Server`.
|
277
|
+
|
278
|
+
### Version History
|
279
|
+
|
280
|
+
Please see the [CHANGELOG](https://github.com/malomalo/condenser/tree/master/CHANGELOG.md)
|
281
|
+
|
282
|
+
## License
|
283
|
+
Condenser is released under the [MIT License](MIT-LICENSE).
|
data/lib/condenser/manifest.rb
CHANGED
@@ -60,7 +60,7 @@ class Condenser
|
|
60
60
|
|
61
61
|
outputs = []
|
62
62
|
args.each do |arg|
|
63
|
-
@environment.resolve
|
63
|
+
@environment.resolve(arg).each do |asset|
|
64
64
|
outputs += add_asset(asset)
|
65
65
|
end
|
66
66
|
end
|
@@ -122,6 +122,9 @@ class Condenser
|
|
122
122
|
def clobber
|
123
123
|
return if !Dir.exist?(dir)
|
124
124
|
|
125
|
+
FileUtils.rm(filename)
|
126
|
+
logger.info "Removed #{filename}"
|
127
|
+
|
125
128
|
Dir.each_child(dir) do |child|
|
126
129
|
FileUtils.rm_r(File.join(dir, child))
|
127
130
|
end
|
data/lib/condenser/version.rb
CHANGED
@@ -22,8 +22,12 @@ class Condenser::ZlibWriter
|
|
22
22
|
@added_mime_types = added_mime_types || ADDED_MIME_TYPES
|
23
23
|
end
|
24
24
|
|
25
|
+
def path(asset)
|
26
|
+
"#{asset.path}.gz"
|
27
|
+
end
|
28
|
+
|
25
29
|
def exist?(asset)
|
26
|
-
::File.exist?(
|
30
|
+
::File.exist?(path(asset))
|
27
31
|
end
|
28
32
|
|
29
33
|
def call(output_directory, asset)
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: condenser
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.0.
|
4
|
+
version: 0.0.8
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Jon Bracy
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date:
|
11
|
+
date: 2020-01-07 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: ruby-ejs
|