Guiarails.com.br

Chapters

1. O que é o Asset Pipeline?
   • Principais Características
   • O que é Impressão Digital e Por Que Eu Deveria Me Importar?
2. Como usar o Asset Pipeline
   • Assets Específicos de Controllers
   • Organização dos Assets
   • Codificando Links para Assets
   • Arquivos de Manifesto e Diretivas
   • Pré-processamento
3. In Development
   • Raise an Error When an Asset is Not Found
   • Turning Digests Off
   • Turning Source Maps On
4. In Production
   • Precompiling Assets
   • Local Precompilation
   • Live Compilation
   • CDNs
5. Customizing the Pipeline
   • CSS Compression
   • JavaScript Compression
   • GZipping Your Assets
   • Using Your Own Compressor
   • Changing the assets Path
   • X-Sendfile Headers
6. Assets Cache Store
7. Adding Assets to Your Gems
8. Making Your Library or Gem a Pre-Processor

1 O que é o Asset Pipeline?

O asset pipeline fornece um framework para concatenar e minificar ou comprimir assets JavaScript e CSS. Ele também tem a habilidade de escrever esses assets em outras linguagens e pré-processadores tais como CoffeeScript, Sass e ERB. Isso permite que os assets da sua aplicação sejam automaticamente combinados com assets de outras gems.

O asset pipeline é implementado pela gem sprockets-rails, e é habilitado por padrão. Você pode desabilitar enquanto está criando uma nova aplicação passando a opção --skip-asset-pipeline.

$ rails new appname --skip-asset-pipeline

O Rails pode facilmente trabalhar com Sass adicionando a gem sassc-rails no seu Gemfile, a qual é usada pelo Sprockets para compilação de Sass:

gem 'sassc-rails'

Para configurar os métodos de compactação do asset, coloque as opções de configuração apropriadas no production.rb - config.assets.css_compressor para o seu CSS e config.assets.js_compressor para seu JavaScript:

config.assets.css_compressor = :yui
config.assets.js_compressor = :terser

1.1 Principais Características

A primeira característica do pipeline é concatenar os assets, o qual pode reduzir o número de requisições que o navegador faz para renderizar uma página web. Os navegadores web são limitados no número de requisições que eles podem fazer em paralelo, portanto, menos solicitações podem significar carregamento mais rápido de sua aplicação.

O Sprockets concatena todos os arquivos JavaScript em um arquivo principal .js e todos os arquivos CSS em um arquivo principal .css. Como você aprenderá mais tarde neste guia, você pode mudar esta estratégia para agrupar arquivos da maneira que quiser. Em produção, o Rails insere uma impressão digital SHA256 dentro de cada nome de arquivo para que o arquivo seja armazenado em cache no navegador. Você pode invalidar o armazenamento cache alterando essa impressão digital, o qual acontece automaticamente sempre que você muda o conteúdo do arquivo.

A segunda característica do asset pipeline é a minificação ou compactação do asset. Para arquivos CSS, isso é feito removendo espaços em branco e comentários. Para JavaScript, mais processos complexos são aplicados. Você pode escolher entre um conjunto de opções ou especificar a sua própria.

A terceira característica do asset pipeline é que permite a codificação dos assets por meio de uma línguagem de alto nível, com pré-compilação até os atuais assets. Línguagens suportadas incluem Sass para CSS, CoffeeScript para JavaScript, e ERB para ambos por padrão.

1.2 O que é Impressão Digital e Por Que Eu Deveria Me Importar?

Impressão digital é uma técnica que faz o nome do arquivo dependente do conteúdo do arquivo. Quando o conteúdo do arquivo muda, o nome do arquivo muda também. Para o conteúdo estático ou que muda com pouca frequência, ele tem uma forma mais fácil para dizer se duas versões do arquivo são idênticas, mesmo através de diferentes servidores ou datas de desenvolvimento.

Quando o nome do arquivo é único e baseado no seu conteúdo, os headers HTTP podem ser configurados para encorajar armazenamento caches em todo lugar (seja em CDNs, em ISPs, nos equipamentos de rede, ou nos navegadores web) para manter suas próprias cópias do conteúdo. Quando o conteúdo é atualizado, a impressão digital mudará. Isso fará com que os clientes remotos requisitem uma nova cópia do conteúdo. Isso é geralmente conhecido como cache busting.

A técnica que o Sprockets usa para impressão digital é inserir um hash do conteúdo no nome, geralmente no final. Por exemplo o arquivo CSS global.css

global-908e25f4bf641868d8683022a5b62f54.css

Essa é a estratégia adotada pelo asset pipeline do Rails.

A antiga estratégia do Rails era anexar uma Query String(string de consulta) baseada em data para cada asset vinculado com um helper interno. Em resumo o código gerado parecia com isso:

/stylesheets/global.css?1309495796

A estratégia de Query String(string de consulta) tinha várias desvantagens:

1. Nem todos os caches irão armazenar o conteúdo onde o nome do arquivo se diferencia apenas por parâmetros de busca

   recommendação do Steve Souders, "...Evitando uma Query String(string de consulta) para recursos de armazenamento de cache". Ele descobriu que nesse caso 5-20% das requisições não irão ser armazenadas em cache. Query String(string de consulta) em particular nem sempre funcionam com alguns CDNs por invalidação de cache.

2. O nome do arquivo pode mudar entre nós em ambientes de multi-servidores.

   A Query String(string de consulta) padrão no Rails 2.x é baseada na data de modificação dos arquivos. Quando os assets são implantados em um cluster, não há garantia que o timestamps será o mesmo, resultando em diferentes valores sendo usados dependendo de qual servidor lida com a requisição.

3. Muita invalidação de cache

   Quando assets estáticos são implementados com novas versões de código, o mtime (horário da última modificação) de todos esses arquivos muda, forçando todos os clientes remotos a encontrarem eles de novo, mesmo quando o conteúdo desses assets não mudaram.

A Impressão digital resolve esses problemas evitando Query String(string de consulta), e garantindo que o nome dos arquivos sejam coerentes com base no seu conteúdo.

A impressão digital é habilitada por padrão para ambos os ambientes desenvolvimento e produção. Você pode habilitar ou desabilitar isso na sua configuração através da opção config.assets.digest.

Mais leitura:

• Otimizar o armazenamento cache (em inglês)
• Acelerando nome dos arquivos: não use Query String(string de consulta) (em inglês)

2 Como usar o Asset Pipeline

Nas versões anteriores do Rails, todos os assets estavam localizados nos subdiretórios abaixo de public, como imagens, javascripts and stylesheets. Com o asset pipeline, a localização recomendada para esses assets é agora o diretório app/assets. Arquivos nesse diretório serão servidos pelo Sprockets middleware.

Os assets podem ainda ser colocados na hierarquia do public. Qualquer asset sob public ainda será servido como um arquivo estático pela aplicação ou servidor web quando config.public_file_server.enabled estiver configurado como true. Você deve usar o app/assets para arquivos que devem ser pré-processados antes de serem servidos.

Em produção, o Rails pré-compila esses arquivos para public/assets por padrão. As cópias dos arquivos pré-compilados serão então servidas como assets estáticos pelo servidor web. Os arquivos em app/assets nunca serão servidos diretamente em produção.

2.1 Assets Específicos de Controllers

Quando você gera um scaffold ou um controller, o Rails também gera um arquivo Cascading Style Sheet (ou SCSS se o sass-rails estiver no Gemfile) para aquele controller. Adicionalmente, quando você gera um scaffold, o Rails também gera o arquivo scaffolds.css (ou scaffolds.scss se o sass-rails estiver no Gemfile.)

Por exemplo, se você gerar um ProjectsController, o Rails também adicionará um novo arquivo em app/assets/stylesheets/projects.scss. Por padrão, os arquivos estarão prontos para serem usados pela sua aplicação imediatamente usando a diretiva require_tree. Veja Arquivos de Manifesto e Diretivas para mais detalhes sobre require_tree.

Você também pode optar por incluir stylesheets específicas do controller e arquivos JavaScript apenas nos seus respectivos diretórios, usando o seguinte:

<%= javascript_include_tag params[:controller] %> ou <%= stylesheet_link_tag params[:controller] %>

Ao fazer isso, certifique-se de que você não está usando a diretiva require_tree, pois isso resultará em seus assets serem incluídos mais de uma vez.

2.2 Organização dos Assets

Os pipeline assets podem ser colocados dentro de uma aplicação nos três locais seguintes: app/assets, lib/assets ou vendor/assets.

• app/assets é destinado aos assets que são proprietários da aplicação, como imagens customizadas, arquivos JavaScript ou folhas de estilo.

• lib/assets é destinado ao código das suas próprias bibliotecas que não se encaixam no escopo da aplicação ou àquelas bibliotecas que são compartilhadas entre aplicações.

• vendor/assets é destinado aos assets que são de propriedade de entidades externas, como código para plugins de JavaScript e frameworks de CSS. Tenha em mente que códigos de terceiros com referências à outros arquivos também processados pelo asset Pipeline (imagens, folhas de estilo, etc.), terão que ser reescritos para usarem auxiliares como asset_path.

2.2.1 Caminhos de Busca

Quando um arquivo é referenciado a partir de um manifesto ou um helper, o Sprockets procura por ele em três locais padrões de assets.

Os três locais padrões são: os diretórios images, javascripts e stylesheets abaixo da pasta app/assets, mas esses subdiretórios não são especiais - qualquer caminho sob assets/* será pesquisado.

Por exemplo, esses arquivos:

app/assets/javascripts/home.js
lib/assets/javascripts/moovinator.js
vendor/assets/javascripts/slider.js
vendor/assets/somepackage/phonebox.js

poderiam ser referenciados em um manifesto da seguinte maneira:

//= require home
//= require moovinator
//= require slider
//= require phonebox

Os assets dentro dos subdiretórios também podem ser acessados.

app/assets/javascripts/sub/something.js

é referenciado como:

//= require sub/something

Você pode visualizar o caminho de busca inspecionando Rails.application.config.assets.paths no console do Rails.

Adicionalmente, além do caminho padrão assets/*, caminhos (completos) podem ser adicionados ao pipeline em config/initializers/assets.rb. Por exemplo:

Rails.application.config.assets.paths << Rails.root.join("lib", "videoplayer", "flash")

Os caminhos são percorridos na ordem em que eles aparecem no caminho de busca. Por padrão, isso significa que os arquivos em app/assets tem precedência, e mascararão caminhos correspondentes em lib e vendor.

É importante notar que os arquivos que você quiser referenciar fora de um manifesto devem ser adicionados ao array de pré-compilação, caso contrário eles não estarão disponíveis no ambiente de produção.

2.2.2 Usando Índices de Arquivos

O Sprockets usa arquivos nomeados como index (com a extensão relevante) para um propósito especial.

Por exemplo, ser você tiver uma biblioteca jQuery com muitos módulos, que é armazenada em lib/assets/javascripts/library_name, o arquivo lib/assets/javascripts/library_name/index.js serve como manifesto para todos os arquivos desta biblioteca. Esse arquivo poderia incluir uma lista de ordenada de todos os arquivos necessários ou uma simples diretiva require_tree.

A biblioteca como um todo pode ser acessada no manifesto da aplicação como:

//= require library_name

Isso simplifica a manutenção e mantém as coisas limpas, permitindo que o código relacionado seja agrupado antes da inclusão em outro lugar.

2.3 Codificando Links para Assets

O Sprockets não adiciona nenhum método para acessar seus assets - você ainda usa as familiares javascript_include_tag e stylesheet_link_tag:

<%= stylesheet_link_tag "application", media: "all" %>
<%= javascript_include_tag "application" %>

Se você estiver usando a gem turbolinks, que é incluída por padrão no Rails, então inclua a opção 'data-turbo-track' que faz com que a Turbo verifique se um asset foi atualizado e então o carrega naquela página:

<%= stylesheet_link_tag "application", media: "all", "data-turbo-track" => "reload" %>
<%= javascript_include_tag "application", "data-turbo-track" => "reload" %>

Em views comuns você pode acessar imagens no diretório app/assets/images como essa:

<%= image_tag "rails.png" %>

Se o pipeline estiver ativo na sua aplicação (e não desativado no contexto do ambiente atual), esse arquivo é servido pelo Sprockets. Se um arquivo existir em public/assets/rails.png ele é servido pelo servidor web.

Alternativamente, uma requisição para um arquivo com um hash SHA256 como public/assets/rails-f90d8a84c707a8dc923fca1ca1895ae8ed0a09237f6992015fef1e11be77c023.png é tratado da mesma maneira. A forma como esses hashes são gerados está coberta na seção Em Produção, posteriormente nesse guia.

O Sprockets procurará através dos caminhos especificados em config.assets.paths, que inclui os caminhos padrões da aplicação e quaisquer caminhos adicionados pelas engines do Rails.

As imagens também podem ser organizadas em subdiretórios se necessário, e então podem ser acessadas pelo nome do diretório na tag:

<%= image_tag "icons/rails.png" %>

2.3.1 CSS e ERB

O asset pipeline avalia automaticamente o ERB. Isso significa que se você adicionar uma extensão erb a um asset CSS (por exemplo, application.css.erb), então helpers como asset_path estarão disponíveis nas suas regras de CSS:

.class { background-image: url(<%= asset_path 'image.png' %>) }

Isso escreve o caminho ao asset em particular que está sendo referenciado. Nesse exemplo, faria sentido ter uma imagem em um dos caminhos carregados de assets, como app/assets/images/image.png, que seria referenciado aqui. Se essa imagem já está disponível em public/assets como um arquivo com uma impressão digital, então aquele caminho é referenciado.

Se você quiser usar URI de dados - um método para embutir a imagem diretamente no arquivo de CSS - você pode usar o helper asset_data_uri.

#logo { background: url(<%= asset_data_uri 'logo.png' %>) }

Isso insere uma URI de dados corretamente formatada no CSS fonte.

Note que a tag de fechamento não pode ser do estilo -%>.

2.3.2 CSS e Sass

Ao utilizar o asset pipeline, os caminhos para os assets devem ser reescritos e o sass-rails provê os helpers -url e -path (hifenizados em Sass, separados por underscore em Ruby) para as seguintes classes de assets: imagem, fonte, vídeo, áudio, JavaScript e folha de estilo.

• image-url("rails.png") returns url(/assets/rails.png)
• image-path("rails.png") returns "/assets/rails.png"

A forma mais genérica também pode ser usada:

• asset-url("rails.png") retorna url(/assets/rails.png)
• asset-path("rails.png") retorna "/assets/rails.png"

2.3.3 JavaScript/CoffeeScript e ERB

Se você adicionar uma extensão erb a um asset JavaScript, fazendo algo como application.js.erb, você pode então usar o helper asset_path no seu código JavaScript:

document.getElementById('logo').src = "<%= asset_path('logo.png') %>"

Isso escreve o caminho ao asset em particular que está sendo referenciado.

2.4 Arquivos de Manifesto e Diretivas

O Sprockets usa arquivos de manifesto para determinar quais assets incluir e servir. Esses arquivos de manifesto contém diretivas - instruções que dirão ao Sprockets quais arquivos solicitar para construir um arquivo CSS ou JavaScript único. Com essas diretivas, o Sprockets carrega os arquivos especificados, processa-os se necessário, concatena-os com em único arquivo e então comprime-os (baseado no valor de Rails.application.config.assets.js_compressor). Ao servir um arquivo ao invés de muitos, o tempo de carregamento das páginas pode ser amplamente reduzido porque o navegador faz menos requisições. A compressão também reduz o tamanho dos arquivos, permitindo ao navegador baixá-los mais rapidamente.

Por exemplo, com um arquivo app/assets/javascripts/application.js contendo as seguintes linhas:

// ...
//= require rails-ujs
//= require turbolinks
//= require_tree .

Nos arquivos JavaScript, as diretivas do Sprocket começam com //=. No caso acima, o arquivo está usando as diretivas require e require_tree. A diretiva require é usada para instruir o Sprockets dos arquivos que você deseja solicitar. Aqui, você está solicitando os arquivos rails-ujs.js e turbolinks.js, que estão disponíveis em algum lugar no caminho de busca do Sprockets. Você não precisa informar as extensões explicitamente. O Sprockets assume que você está solicitando um arquivo .js quando feito de dentro de um arquivo .js.

A diretiva require_tree instrui ao Sprockets para recursivamente incluir todos os arquivos JavaScript no diretório especificado no output. Esses caminhos deverão ser especificados de maneira relativa ao arquivo de manifesto. Você também pode usar a diretiva require_directory, que inclui todos os arquivos JavaScript somente do diretório especificado, sem recursão.

As diretivas são processadas de cima para baixo, mas a ordem na qual os arquivos são incluídos pelo require_tree não é garantida. Você não deve confiar em nenhuma ordem particular entre eles. Se você precisar garantir que um JavaScript em particular termine acima de outro no arquivo concatenado, solicite o pré-requisito antes no manifesto. Note que a família de diretivas require previne arquivos de serem incluídos duas vezes no output.

O Rails também cria um arquivo padrão app/assets/stylesheets/application.css que contém essas linhas:

/* ...
 *= require_self
 *= require_tree .
 */

O Rails cria o app/assets/stylesheets/application.css independentemente se a opção --skip-asset-pipeline é usada ao criar uma nova aplicação Rails. Isso permite que você facilmente adicione o asset pipelining mais tarde se assim o quiser.

As diretivas que funcionam nos arquivos JavaScript também funcionam nas folhas de estilo (que obviamente incluem folhas de estilo além de arquivos JavaScript). A diretiva require_tree em um manifesto CSS funciona da mesma maneira que no JavaScript, solicitando todas as folhas de estilo do diretório corrente.

Nesse exemplo, require_self é usado. Isso coloca o CSS contido dentro do arquivo (se houver algum) na localização exata da chamada require_self.

Você pode fazer globbing dos arquivos usando @import "*" e @import "**/*" para adicionar a árvore completa, que é equivalente a como o require_tree funciona. Veja a documentação do sass-rails para mais informações e ressalvas importantes.

Você pode ter quantos arquivos de manifesto quiser. Por exemplo, os manifestos admin.css e admin.js podem conter os arquivos JS e CSS que são usados pela seção de admin de uma aplicação.

As mesmas afirmações sobre ordens feitas acima também se aplicam. Em particular, você pode especificar arquivos individuais e eles serão compilados na ordem especificada. Por exemplo, você pode concatenar três arquivos CSS juntos da seguinte maneira:

/* ...
 *= require reset
 *= require layout
 *= require chrome
 */

2.5 Pré-processamento

As extensões de arquivos usadas em um asset determinam qual pré-processamento é aplicado. Quando um controller ou um scaffold é gerado com o gemset padrão do Rails, um arquivo SCSS é gerado no lugar de um arquivo comum CSS. O exemplo usado anteriormente era um controller chamado "projects", que gerou um arquivo app/assets/stylesheets/projects.scss.

Em modo de desenvolvimento, se o asset pipeline estiver desabilitado, quando esses arquivos são solicitados, eles serão processados pelos processors especificados pela gem sass-rails e então enviados de volta ao navegador como CSS. Quando o asset pipelining está habilitado, esses arquivos são pré-processados e colocados no diretório public/assets, para serem servidos seja pela aplicação Rails ou pelo servidor web.

Camadas adicionais de pré-processamento podem ser solicitadas ao se adicionar outras extensões, onde cada extensão é processada da direita para a esquerda. Essas devem ser usadas para que o processamento seja aplicado. Por exemplo, uma folha de estilos chamada app/assets/stylesheets/projects.scss.erb é primeiramente processada como ERB, depois como SCSS e finalmente servida como CSS. O mesmo se aplica a um arquivo JavaScript - app/assets/javascripts/projects.coffee.erb, que é processado como ERB, depois CoffeeScript e então servido como JavaScript.

Tenha em mente que a ordem desses pré-processadores é importante. Por exemplo, se você chamou seu arquivo JavaScript de app/assets/javascripts/projects.erb.coffee, então ele seria processado pelo interpretador do CoffeeScript primeiro, que não entende ERB, o que te causaria problemas.

3 In Development

In development mode, assets are served as a concatenated file.

This manifest app/assets/javascripts/application.js:

//= require core
//= require projects
//= require tickets

would generate this HTML:

<script src="/assets/application-728742f3b9daa182fe7c831f6a3b8fa87609b4007fdc2f87c134a07b19ad93fb.js"></script>

3.1 Raise an Error When an Asset is Not Found

If you are using sprockets-rails >= 3.2.0 you can configure what happens when an asset lookup is performed and nothing is found. If you turn off "asset fallback" then an error will be raised when an asset cannot be found.

config.assets.unknown_asset_fallback = false

If "asset fallback" is enabled then when an asset cannot be found the path will be output instead and no error raised. The asset fallback behavior is disabled by default.

3.2 Turning Digests Off

You can turn off digests by updating config/environments/development.rb to include:

config.assets.digest = false

When this option is true, digests will be generated for asset URLs.

3.3 Turning Source Maps On

You can turn on source maps by updating config/environments/development.rb to include:

config.assets.debug = true

When debug mode is on, Sprockets will generate a Source Map for each asset. This allows you to debug each file individually in your browser's developer tools.

Assets are compiled and cached on the first request after the server is started. Sprockets sets a must-revalidate Cache-Control HTTP header to reduce request overhead on subsequent requests - on these the browser gets a 304 (Not Modified) response.

If any of the files in the manifest change between requests, the server responds with a new compiled file.

4 In Production

In the production environment Sprockets uses the fingerprinting scheme outlined above. By default Rails assumes assets have been precompiled and will be served as static assets by your web server.

During the precompilation phase an SHA256 is generated from the contents of the compiled files, and inserted into the filenames as they are written to disk. These fingerprinted names are used by the Rails helpers in place of the manifest name.

For example this:

<%= javascript_include_tag "application" %>
<%= stylesheet_link_tag "application" %>

generates something like this:

<script src="/assets/application-908e25f4bf641868d8683022a5b62f54.js"></script>
<link href="/assets/application-4dd5b109ee3439da54f5bdfd78a80473.css" rel="stylesheet" />

The fingerprinting behavior is controlled by the config.assets.digest initialization option (which defaults to true).

4.1 Precompiling Assets

Rails comes bundled with a command to compile the asset manifests and other files in the pipeline.

Compiled assets are written to the location specified in config.assets.prefix. By default, this is the /assets directory.

You can call this command on the server during deployment to create compiled versions of your assets directly on the server. See the next section for information on compiling locally.

The command is:

$ RAILS_ENV=production rails assets:precompile

This links the folder specified in config.assets.prefix to shared/assets. If you already use this shared folder you'll need to write your own deployment command.

It is important that this folder is shared between deployments so that remotely cached pages referencing the old compiled assets still work for the life of the cached page.

The default matcher for compiling files includes application.js, application.css and all non-JS/CSS files (this will include all image assets automatically) from app/assets folders including your gems:

[ Proc.new { |filename, path| path =~ /app\/assets/ && !%w(.js .css).include?(File.extname(filename)) },
/application.(css|js)$/ ]

If you have other manifests or individual stylesheets and JavaScript files to include, you can add them to the precompile array in config/initializers/assets.rb:

Rails.application.config.assets.precompile += %w( admin.js admin.css )

The command also generates a .sprockets-manifest-randomhex.json (where randomhex is a 16-byte random hex string) that contains a list with all your assets and their respective fingerprints. This is used by the Rails helper methods to avoid handing the mapping requests back to Sprockets. A typical manifest file looks like:

{"files":{"application-aee4be71f1288037ae78b997df388332edfd246471b533dcedaa8f9fe156442b.js":{"logical_path":"application.js","mtime":"2016-12-23T20:12:03-05:00","size":412383,
"digest":"aee4be71f1288037ae78b997df388332edfd246471b533dcedaa8f9fe156442b","integrity":"sha256-ruS+cfEogDeueLmX3ziDMu39JGRxtTPc7aqPn+FWRCs="},
"application-86a292b5070793c37e2c0e5f39f73bb387644eaeada7f96e6fc040a028b16c18.css":{"logical_path":"application.css","mtime":"2016-12-23T19:12:20-05:00","size":2994,
"digest":"86a292b5070793c37e2c0e5f39f73bb387644eaeada7f96e6fc040a028b16c18","integrity":"sha256-hqKStQcHk8N+LA5fOfc7s4dkTq6tp/lub8BAoCixbBg="},
"favicon-8d2387b8d4d32cecd93fa3900df0e9ff89d01aacd84f50e780c17c9f6b3d0eda.ico":{"logical_path":"favicon.ico","mtime":"2016-12-23T20:11:00-05:00","size":8629,
"digest":"8d2387b8d4d32cecd93fa3900df0e9ff89d01aacd84f50e780c17c9f6b3d0eda","integrity":"sha256-jSOHuNTTLOzZP6OQDfDp/4nQGqzYT1DngMF8n2s9Dto="},
"my_image-f4028156fd7eca03584d5f2fc0470df1e0dbc7369eaae638b2ff033f988ec493.png":{"logical_path":"my_image.png","mtime":"2016-12-23T20:10:54-05:00","size":23414,
"digest":"f4028156fd7eca03584d5f2fc0470df1e0dbc7369eaae638b2ff033f988ec493","integrity":"sha256-9AKBVv1+ygNYTV8vwEcN8eDbxzaequY4sv8DP5iOxJM="}},
"assets":{"application.js":"application-aee4be71f1288037ae78b997df388332edfd246471b533dcedaa8f9fe156442b.js",
"application.css":"application-86a292b5070793c37e2c0e5f39f73bb387644eaeada7f96e6fc040a028b16c18.css",
"favicon.ico":"favicon-8d2387b8d4d32cecd93fa3900df0e9ff89d01aacd84f50e780c17c9f6b3d0eda.ico",
"my_image.png":"my_image-f4028156fd7eca03584d5f2fc0470df1e0dbc7369eaae638b2ff033f988ec493.png"}}

The default location for the manifest is the root of the location specified in config.assets.prefix ('/assets' by default).

4.1.1 Far-future Expires Header

Precompiled assets exist on the file system and are served directly by your web server. They do not have far-future headers by default, so to get the benefit of fingerprinting you'll have to update your server configuration to add those headers.

For Apache:

# The Expires* directives requires the Apache module
# `mod_expires` to be enabled.
<Location /assets/>
  # Use of ETag is discouraged when Last-Modified is present
  Header unset ETag
  FileETag None
  # RFC says only cache for 1 year
  ExpiresActive On
  ExpiresDefault "access plus 1 year"
</Location>

For NGINX:

location ~ ^/assets/ {
  expires 1y;
  add_header Cache-Control public;

  add_header ETag "";
}

4.2 Local Precompilation

Sometimes, you may not want or be able to compile assets on the production server. For instance, you may have limited write access to your production filesystem, or you may plan to deploy frequently without making any changes to your assets.

In such cases, you can precompile assets locally — that is, add a finalized set of compiled, production-ready assets to your source code repository before pushing to production. This way, they do not need to be precompiled separately on the production server upon each deployment.

As above, you can perform this step using

$ RAILS_ENV=production rails assets:precompile

Note the following caveats:

• If precompiled assets are available, they will be served — even if they no longer match the original (uncompiled) assets, even on the development server.

  To ensure that the development server always compiles assets on-the-fly (and thus always reflects the most recent state of the code), the development environment must be configured to keep precompiled assets in a different location than production does. Otherwise, any assets precompiled for use in production will clobber requests for them in development (i.e., subsequent changes you make to assets will not be reflected in the browser).

  You can do this by adding the following line to config/environments/development.rb:

  config.assets.prefix = "/dev-assets"
  

  Copy

• The asset precompile task in your deployment tool (e.g., Capistrano) should be disabled.

• Any necessary compressors or minifiers must be available on your development system.

4.3 Live Compilation

In some circumstances you may wish to use live compilation. In this mode all requests for assets in the pipeline are handled by Sprockets directly.

To enable this option set:

config.assets.compile = true

On the first request the assets are compiled and cached as outlined in Assets Cache Store, and the manifest names used in the helpers are altered to include the SHA256 hash.

Sprockets also sets the Cache-Control HTTP header to max-age=31536000. This signals all caches between your server and the client browser that this content (the file served) can be cached for 1 year. The effect of this is to reduce the number of requests for this asset from your server; the asset has a good chance of being in the local browser cache or some intermediate cache.

This mode uses more memory, performs more poorly than the default, and is not recommended.

If you are deploying a production application to a system without any pre-existing JavaScript runtimes, you may want to add one to your Gemfile:

group :production do
  gem 'mini_racer'
end

4.4 CDNs

CDN stands for Content Delivery Network, they are primarily designed to cache assets all over the world so that when a browser requests the asset, a cached copy will be geographically close to that browser. If you are serving assets directly from your Rails server in production, the best practice is to use a CDN in front of your application.

A common pattern for using a CDN is to set your production application as the "origin" server. This means when a browser requests an asset from the CDN and there is a cache miss, it will grab the file from your server on the fly and then cache it. For example if you are running a Rails application on example.com and have a CDN configured at mycdnsubdomain.fictional-cdn.com, then when a request is made to mycdnsubdomain.fictional- cdn.com/assets/smile.png, the CDN will query your server once at example.com/assets/smile.png and cache the request. The next request to the CDN that comes in to the same URL will hit the cached copy. When the CDN can serve an asset directly the request never touches your Rails server. Since the assets from a CDN are geographically closer to the browser, the request is faster, and since your server doesn't need to spend time serving assets, it can focus on serving application code as fast as possible.

4.4.1 Set up a CDN to Serve Static Assets

To set up your CDN you have to have your application running in production on the internet at a publicly available URL, for example example.com. Next you'll need to sign up for a CDN service from a cloud hosting provider. When you do this you need to configure the "origin" of the CDN to point back at your website example.com. Check your provider for documentation on configuring the origin server.

The CDN you provisioned should give you a custom subdomain for your application such as mycdnsubdomain.fictional-cdn.com (note fictional-cdn.com is not a valid CDN provider at the time of this writing). Now that you have configured your CDN server, you need to tell browsers to use your CDN to grab assets instead of your Rails server directly. You can do this by configuring Rails to set your CDN as the asset host instead of using a relative path. To set your asset host in Rails, you need to set config.asset_host in config/environments/production.rb:

config.asset_host = 'mycdnsubdomain.fictional-cdn.com'

You can also set this value through an environment variable to make running a staging copy of your site easier:

config.asset_host = ENV['CDN_HOST']

Once you have configured your server and your CDN, asset paths from helpers such as:

<%= asset_path('smile.png') %>

Will be rendered as full CDN URLs like http://mycdnsubdomain.fictional-cdn.com/assets/smile.png (digest omitted for readability).

If the CDN has a copy of smile.png, it will serve it to the browser, and your server doesn't even know it was requested. If the CDN does not have a copy, it will try to find it at the "origin" example.com/assets/smile.png, and then store it for future use.

If you want to serve only some assets from your CDN, you can use custom :host option your asset helper, which overwrites value set in config.action_controller.asset_host.

<%= asset_path 'image.png', host: 'mycdnsubdomain.fictional-cdn.com' %>

4.4.2 Customize CDN Caching Behavior

A CDN works by caching content. If the CDN has stale or bad content, then it is hurting rather than helping your application. The purpose of this section is to describe general caching behavior of most CDNs. Your specific provider may behave slightly differently.

4.4.2.1 CDN Request Caching

While a CDN is described as being good for caching assets, it actually caches the entire request. This includes the body of the asset as well as any headers. The most important one being Cache-Control, which tells the CDN (and web browsers) how to cache contents. This means that if someone requests an asset that does not exist, such as /assets/i-dont-exist.png, and your Rails application returns a 404, then your CDN will likely cache the 404 page if a valid Cache-Control header is present.

4.4.2.2 CDN Header Debugging

One way to check the headers are cached properly in your CDN is by using curl. You can request the headers from both your server and your CDN to verify they are the same:

$ curl -I http://www.example/assets/application-
d0e099e021c95eb0de3615fd1d8c4d83.css
HTTP/1.1 200 OK
Server: Cowboy
Date: Sun, 24 Aug 2014 20:27:50 GMT
Connection: keep-alive
Last-Modified: Thu, 08 May 2014 01:24:14 GMT
Content-Type: text/css
Cache-Control: public, max-age=2592000
Content-Length: 126560
Via: 1.1 vegur

Versus the CDN copy:

$ curl -I http://mycdnsubdomain.fictional-cdn.com/application-
d0e099e021c95eb0de3615fd1d8c4d83.css
HTTP/1.1 200 OK Server: Cowboy Last-
Modified: Thu, 08 May 2014 01:24:14 GMT Content-Type: text/css
Cache-Control:
public, max-age=2592000
Via: 1.1 vegur
Content-Length: 126560
Accept-Ranges:
bytes
Date: Sun, 24 Aug 2014 20:28:45 GMT
Via: 1.1 varnish
Age: 885814
Connection: keep-alive
X-Served-By: cache-dfw1828-DFW
X-Cache: HIT
X-Cache-Hits:
68
X-Timer: S1408912125.211638212,VS0,VE0

Check your CDN documentation for any additional information they may provide such as X-Cache or for any additional headers they may add.

4.4.2.3 CDNs and the Cache-Control Header

The Cache-Control header describes how a request can be cached. When no CDN is used, a browser will use this information to cache contents. This is very helpful for assets that are not modified so that a browser does not need to re-download a website's CSS or JavaScript on every request. Generally we want our Rails server to tell our CDN (and browser) that the asset is "public". That means any cache can store the request. Also we commonly want to set max-age which is how long the cache will store the object before invalidating the cache. The max-age value is set to seconds with a maximum possible value of 31536000, which is one year. You can do this in your Rails application by setting

config.public_file_server.headers = {
  'Cache-Control' => 'public, max-age=31536000'
}

Now when your application serves an asset in production, the CDN will store the asset for up to a year. Since most CDNs also cache headers of the request, this Cache-Control will be passed along to all future browsers seeking this asset. The browser then knows that it can store this asset for a very long time before needing to re-request it.

4.4.2.4 CDNs and URL-based Cache Invalidation

Most CDNs will cache contents of an asset based on the complete URL. This means that a request to

http://mycdnsubdomain.fictional-cdn.com/assets/smile-123.png

Will be a completely different cache from

http://mycdnsubdomain.fictional-cdn.com/assets/smile.png

If you want to set far future max-age in your Cache-Control (and you do), then make sure when you change your assets that your cache is invalidated. For example when changing the smiley face in an image from yellow to blue, you want all visitors of your site to get the new blue face. When using a CDN with the Rails asset pipeline config.assets.digest is set to true by default so that each asset will have a different file name when it is changed. This way you don't have to ever manually invalidate any items in your cache. By using a different unique asset name instead, your users get the latest asset.

5 Customizing the Pipeline

5.1 CSS Compression

One of the options for compressing CSS is YUI. The YUI CSS compressor provides minification.

The following line enables YUI compression, and requires the yui-compressor gem.

config.assets.css_compressor = :yui

The other option for compressing CSS if you have the sass-rails gem installed is

config.assets.css_compressor = :sass

5.2 JavaScript Compression

Possible options for JavaScript compression are :terser, :closure and :yui. These require the use of the terser, closure-compiler or yui-compressor gems, respectively.

Take the terser gem, for example. This gem wraps Terser (written for Node.js) in Ruby. It compresses your code by removing white space and comments, shortening local variable names, and performing other micro-optimizations such as changing if and else statements to ternary operators where possible.

The following line invokes terser for JavaScript compression.

config.assets.js_compressor = :terser

5.3 GZipping Your Assets

By default, gzipped version of compiled assets will be generated, along with the non-gzipped version of assets. Gzipped assets help reduce the transmission of data over the wire. You can configure this by setting the gzip flag.

config.assets.gzip = false # disable gzipped assets generation

Refer to your web server's documentation for instructions on how to serve gzipped assets.

5.4 Using Your Own Compressor

The compressor config settings for CSS and JavaScript also take any object. This object must have a compress method that takes a string as the sole argument and it must return a string.

class Transformer
  def compress(string)
    do_something_returning_a_string(string)
  end
end

To enable this, pass a new object to the config option in application.rb:

config.assets.css_compressor = Transformer.new

5.5 Changing the assets Path

The public path that Sprockets uses by default is /assets.

This can be changed to something else:

config.assets.prefix = "/some_other_path"

This is a handy option if you are updating an older project that didn't use the asset pipeline and already uses this path or you wish to use this path for a new resource.

5.6 X-Sendfile Headers

The X-Sendfile header is a directive to the web server to ignore the response from the application, and instead serve a specified file from disk. This option is off by default, but can be enabled if your server supports it. When enabled, this passes responsibility for serving the file to the web server, which is faster. Have a look at send_file on how to use this feature.

Apache and NGINX support this option, which can be enabled in config/environments/production.rb:

# config.action_dispatch.x_sendfile_header = "X-Sendfile" # for Apache
# config.action_dispatch.x_sendfile_header = 'X-Accel-Redirect' # for NGINX

6 Assets Cache Store

By default, Sprockets caches assets in tmp/cache/assets in development and production environments. This can be changed as follows:

config.assets.configure do |env|
  env.cache = ActiveSupport::Cache.lookup_store(:memory_store,
                                                { size: 32.megabytes })
end

To disable the assets cache store:

config.assets.configure do |env|
  env.cache = ActiveSupport::Cache.lookup_store(:null_store)
end

7 Adding Assets to Your Gems

Assets can also come from external sources in the form of gems.

A good example of this is the jquery-rails gem. This gem contains an engine class which inherits from Rails::Engine. By doing this, Rails is informed that the directory for this gem may contain assets and the app/assets, lib/assets and vendor/assets directories of this engine are added to the search path of Sprockets.

8 Making Your Library or Gem a Pre-Processor

Sprockets uses Processors, Transformers, Compressors, and Exporters to extend Sprockets functionality. Have a look at Extending Sprockets to learn more. Here we registered a preprocessor to add a comment to the end of text/css (.css) files.

module AddComment
  def self.call(input)
    { data: input[:data] + "/* Hello From my sprockets extension */" }
  end
end

Now that you have a module that modifies the input data, it's time to register it as a preprocessor for your mime type.

Sprockets.register_preprocessor 'text/css', AddComment

Feedback

Você é incentivado a ajudar a melhorar a qualidade deste guia.

Por favor, contribua caso veja quaisquer erros, inclusive erros de digitação. Para começar, você pode ler nossa sessão de contribuindo com a documentação.

Você também pode encontrar conteúdo incompleto ou coisas que não estão atualizadas. Por favor, adicione qualquer documentação em falta na main do Rails. Certifique-se de checar o Edge Guides (en-US) primeiro para verificar se o problema já foi resolvido ou não no branch main. Verifique as Diretrizes do Guia Ruby on Rails para estilo e convenções.

Se, por qualquer motivo, você encontrar algo para consertar, mas não conseguir consertá-lo, por favor abra uma issue no nosso Guia.

E por último, mas não menos importante, qualquer tipo de discussão sobre a documentação do Ruby on Rails é muito bem vinda na forum oficial do Ruby on Rails e nas issues do Guia em português.