| Logical path |
Source file on disk |
| application.js |
app/assets/javascripts/application.js |
| models/project.js |
app/assets/javascripts/models/project.js |
| hello.js |
app/assets/javascripts/hello.coffee |
> Note: For assets that are compiled or transpiled, you may 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.
## File Order Processing
By default files are processed in alphabetical order. This behavior can impact
your asset compilation when one asset needs to be loaded before another.
For example if you have an `application.js` and it loads another directory
```js
import initializers from 'config/initializers/*';
initializers.forEach((i) => i());
```
The files in that directory will be loaded in alphabetical order. If the directory
looks like this:
```sh
$ ls -1 config/initializers/
alpha.js
beta.js
gamma.js
```
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
order dependent you can either rename the files or require individual files
manually:
```js
import alpha from 'config/initializers/alpha';
import beta from 'config/initializers/beta';
import gamma from 'config/initializers/gamma';
gamma();
alpha();
beta();
```
## Cache
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.
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.
For example if you have an `application.js` and it is made up of `a.js`, `b.js`,
all the way to `z.js`
```js
import 'a';
import 'b';
// ...
import 'z';
```
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`).
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.
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.
In Rails you can force a "clean" install by clearing the `public/assets` and
`tmp/cache/assets` directories.
### Invoking Ruby with ERB
Condenser provides an ERB engine for preprocessing assets using embedded Ruby
code. Append `.erb` to a CSS or JavaScript asset's filename to enable the ERB engine.
For example if you have an `app/application/javascripts/app_name.js.erb`
you could have this in the template
```js
var app_name = "<%= ENV['APP_NAME'] %>";
```
Generated files are cached. If you're using an `ENV` var then
when you change then ENV var the asset will be forced to
recompile. This behavior is only true for environment variables,
if you are pulling a value from somewhere else, such as a database,
must manually invalidate the cache to see the change.
If you're using Rails, there are helpers you can use such as `asset_url`
that will cause a recompile if the value changes.
For example if you have this in your `application.css.erb`
``` css.erb
.logo {
background: url(<%= asset_url("logo.png") %>)
}
```
When you modify the `logo.png` on disk, it will force `application.css` to be
recompiled so that the fingerprint will be correct in the generated asset.
### Styling with Sass and SCSS
[Sass](http://sass-lang.com/) is a language that compiles to CSS and
adds features like nested rules, variables, mixins and selector
inheritance.
If the `sassc` gem is available to your application, you can use Sass
to write CSS assets in Condenser.
Condenser supports both Sass syntaxes. For the original
whitespace-sensitive syntax, use the extension `.sass`. For the
new SCSS syntax, use the extension `.scss`.
In Rails if you have `app/application/stylesheets/foo.scss` it can
be referenced with `<%= asset_path("foo.css") %>`. When referencing
an asset in Rails, always specify the extension you want. Condenser will
convert `foo.scss` to `foo.css`.
## Javascript, ES#, & ES Modules
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/).
```js
// app/assets/javascript/application.js
var square = (n) => n * n
console.log(square);
```
Start a Rails server in development mode and visit
`localhost:3000/assets/application.js`, and this asset will be transpiled to
JavaScript:
```js
var square = function square(n) {
return n * n;
};
console.log(square);
```
### JavaScript Templating with EJS
Condenser supports *JavaScript templates* for client-side rendering of
strings or markup. JavaScript templates have the special format
extension `.jst` and are compiled to JavaScript functions.
The templates can then be imported. When invoked they will render the template
as a string that can be inserted into the DOM.
```javascript