Tout Ce Que Vous Devez Savoir Sur le Pipeline d’Actifs Rails

Qu’est-ce que le pipeline d’actifs ?

Si vous créez une application Rails, vous avez probablement entendu parler du pipeline d’actifs. Le pipeline d’actifs peut être considéré comme les outils et les mécanismes par lesquels les fichiers Javascript, les feuilles de style et les images sont traités et préparés pour être utilisés par le navigateur. Ces processus peuvent réduire et compresser des actifs, ainsi que des actifs de pré-traitement écrits dans d’autres langages tels que Coffeescript ou Sass.

Le pipeline d’actifs a été créé pour résoudre divers problèmes liés aux actifs statiques. L’un de ces problèmes est que chaque actif spécifié séparément dans le balisage HTML doit être récupéré séparément, ce qui entraîne un nombre plus élevé de requêtes HTTP et, à la fin, un temps de chargement plus long. Les fichiers Javascript et CSS bruts peuvent également gaspiller beaucoup de bande passante avec des commentaires, des espaces blancs supplémentaires et des noms de variables longs. Un autre problème qui se pose concerne la mise en cache. Lorsque vous diffusez un fichier Javascript à partir de votre serveur, par exemple, le navigateur met automatiquement en cache ce fichier pendant un certain temps. Cela améliore le temps de chargement des pages, mais que se passe-t-il si cet actif change ultérieurement? Le navigateur ne le saura pas, il continuera donc à utiliser l’actif mis en cache jusqu’à l’expiration de sa durée de vie. Enfin, des langages tels que Coffeescript, Sass, Less et Erb ont facilité l’organisation et l’écriture de Javascript et de CSS, mais le navigateur ne peut pas les interpréter directement, un pré-processeur est donc nécessaire pour convertir ces fichiers en leurs homologues appropriés avant qu’ils ne soient envoyés au navigateur.

Le pipeline d’actifs, dans sa bienveillance, peut résoudre tous les problèmes ci-dessus lorsqu’il est utilisé correctement. Il peut compiler plusieurs actifs en un seul, réduire et compresser les actifs, fournir une digestion des actifs pour éviter les problèmes de mise en cache, et peut pré-traiter d’autres langages et les transformer en Javascript et CSS.

Cet article couvre une variété de sujets liés au pipeline d’actifs:

• les bases de l’utilisation du pipeline d’actifs
• meilleures pratiques pour structurer où placer vos actifs
• comment utiliser le tableau de précompilation pour spécifier quels fichiers sont traités par le pipeline d’actifs
• comment tirer parti de Sass et Coffeescript
• comment utiliser les méthodes Rails asset Helper, et
• quelques pièges

Utilisation de base

Il existe deux façons de base d’utiliser le pipeline d’actifs:

1. Lors de l’exécution d’un serveur en mode développement, il pré-traite et prépare automatiquement vos actifs à la volée.
2. En mode production, vous l’utiliserez probablement pour pré-traiter, versionner, compresser et compiler vos ressources. Vous pouvez le faire en exécutant la commande suivante:

1

bundle exec rake assets:precompile

Cela créera (par défaut) un répertoire assets dans votre dossier public/. Il ajoutera ensuite tous les fichiers compressés et compilés dans ce répertoire, dans les formats appropriés et avec les nouvelles versions digérées. Vous pouvez ensuite configurer Nginx ou Apache pour serveur ces fichiers directement afin que Rails n’ait pas à les livrer (et exécuter le prétraitement à la volée, etc.) lui-même.

N’oubliez pas que les valeurs par défaut peuvent être modifiées, donc si les choses ne fonctionnent pas comme prévu, vérifiez le fichier de configuration de votre application dans config/application.rb. Dans Rails 4, la gestion des actifs est généralement configurée en config/initializers/assets.rb.

Structure des fichiers

Il est important d’organiser vos actifs de manière compréhensible pour vous et de faciliter les fonctionnalités existantes du pipeline d’actifs. La première chose à savoir est que tous vos Javascript, feuilles de style et images personnalisés doivent être placés dans le répertoire app/assets/. Par défaut, il existe un dossier chacun pour javascripts, stylesheets et images. Vous pouvez également ajouter fonts, audios et videos au répertoire app/assets/ pour ces types d’actifs. Tout le code tiers que vous utilisez (par exemple, jQuery, backbone.js, etc.) doit être placé dans le répertoire vendor/assets/:

1234567891011

rails-app/ app/ assets/ images/ # Image assets javascripts/ # Custom Javascript/coffeescript stylesheets/ # Custom CSS/Sass ... vendor/ assets/ javascripts/ # Javascript libraries, etc. stylesheets/ # Vendor themes, javascript library themes, etc.

Étant donné que votre serveur Web serveur automatiquement des fichiers statiques à partir du répertoire public/, pourquoi tous les actifs Javascript, image et feuille de style ne devraient-ils pas y être placés ? D’une part, rien dans le dossier public ne sera prétraité, compilé ou compressé automatiquement, donc en y mettant des actifs, vous contournez complètement le pipeline d’actifs et perdez tous ses avantages. Lorsque vous y mettez des actifs, vous perdez également la possibilité de les référencer facilement dans votre code Rails. Vous pouvez avoir une vue, par exemple, qui a le code suivant:

12345678910

# app/assets/images/logo.png= image_tag('logo')# Outputs something like <img src="/assets/logo-.png" /># public/images/logo.png= image_tag('/images/logo.png')# Outputs something like# <img src="/images/logo.png" />

Dans le deuxième scénario (public/images/logo.png), le site ne fonctionnera que s’il est livré à partir du répertoire de base. Il ne peut pas non plus tirer parti de la gestion des versions du fichier par le pipeline d’actifs.

Précompilation

Vous vous demandez peut-être maintenant si tout ce que vous mettez dans le dossier app/assets/javascripts/ sera automatiquement précompilé pour votre application. Heureusement, le pipeline d’actifs fournit un moyen de spécifier quels fichiers sont compilés et dans quel ordre. Par défaut, application.css et application.js (ou leurs équivalents sass / coffeescript), ainsi que tous les actifs non Javascript et non CSS sont inclus. Pour inclure un fichier CSS ou Javascript autre que l’application.css et application.js, vous devez l’exiger de l’une des deux manières suivantes:

1. Ajoutez-le au tableau de précompilation dans config/initializers/assets.rb (Rails 4) ou dans votre fichier de configuration d’application (par exemple config/application.rb), ou
2. Incluez le fichier dans le manifeste de votre actif ou dans l’un des manifestes de son sous-fichier.

La première option ressemble à ceci:

12

# In config/initializers/assets.rbRails.application.config.assets.precompile += %w( some-other-file.js even-another.css )

Cette option est la meilleure pour les fichiers qu’il est logique d’inclure uniquement sur certaines pages et ne doit pas être inclus sur d’autres. Par exemple, si vous avez une partie de votre site qui sera utilisée comme widget intégré iframe, vous voudrez peut-être uniquement que widget.js et widget.css, ou similaire, soient utilisés sur cette page. Ces fichiers devraient être ajoutés au tableau de précompilation comme indiqué ci-dessus.

La deuxième option est ce qui devrait être utilisé la plupart du temps, et permet à vos fichiers Javascript et CSS d’être compilés en une seule application.js et une application.fichier css. Le manifeste est écrit en haut de l’actif applicable.

Dans coffeescript, cela ressemble à ceci:

12345

# In application.coffee##= require jquery#= require jquery_ujs#= require_tree .

Le manifeste ci-dessus inclura jQuery, l’adaptateur de script discret jQuery Rails (jquery_ujs) et tous les fichiers de l’arborescence actuelle (c’est-à-dire app/assets/javascript/*). Notez que require_tree ne compile pas les actifs de manière récursive via des répertoires. Si vous avez un dossier de fichiers que vous souhaitez inclure, vous devrez également l’ajouter au manifeste:

1

#= require_tree ./components

Une autre directive manifeste est require_self, qui est utilisée pour inclure le Javascript du fichier actuel à ce point de la chaîne. Ce qui précède, avec un require_self peut être écrit dans un fichier .js comme suit:

1234567

// In application.js////= require jquery//= require jquery_ujs//= require_tree .//= require_tree ./components//= require_self

Les manifestes Sass/CSS utilisent le même format de base, mais avec le style de commentaire approprié:

123456

/** In application.css * *= require reset *= require global *= require layout */

Notez que lors de l’utilisation de Sass, vous devrez utiliser sa règle @import pour tirer parti des variables et des mixins, car chaque fichier compilé par le manifeste a sa propre portée.

Soyez prudent avec votre utilisation de la directive require_tree. Les actifs de l’arborescence seront inclus dans l’ordre alphabétique, ce qui signifie que si un fichier qui commence par « a » dépend d’un fichier qui commence par « z », vous pourriez rencontrer des problèmes où les éléments nécessaires ne sont pas disponibles lorsque le Javascript est évalué par le navigateur. Ce problème peut être évité en utilisant les gardes jQuery(document).ready() ou window.onload appropriés, en spécifiant un ordre manuellement, ou en préfixant les fichiers avec des nombres tels que 01_, 02_:

12345

# application.js# Note that the `.js` isn't needed at the end of the filename.##= require subfolder/library#= require subfolder/depends-on-library

N’oubliez pas que tout fichier Javascript ou CSS précompilé peut contenir un manifeste en haut, vous pouvez donc utiliser les fichiers des sous-dossiers pour simplifier votre manifeste de niveau supérieur.

Sass et Coffescript, et Assistants d’actifs Rails

J’ai un peu mentionné Sass et Coffeescript dans les sections ci-dessus, mais je ne suis pas encore entré dans ce qu’ils sont. Si vous les connaissez déjà, n’hésitez pas à passer à la section « Assistants d’actifs Rails ».

Sass et Coffeescript

Sass et Coffeescript sont des langages qui utilisent des préprocesseurs pour transformer leur syntaxe en CSS et Javascript, respectivement. Il existe plusieurs autres langages prétraités tels que Typescript et Less, mais Sass et Coffeescript sont inclus par défaut avec Rails, et sont probablement les plus populaires. Je n’entrerai pas dans les détails ici sur ces langues, alors veuillez consulter les liens ci-dessus pour plus d’informations.

D’après mon expérience, alors que Sass et Coffeescript fournissent beaucoup de sucre syntaxique (jolies fonctionnalités de code), le fait que des exceptions soient levées pour du code invalide au stade du prétraitement suffit à justifier leur utilisation. Coffeescript enveloppe automatiquement votre code par fichier et ajoute le mot-clé var à vos variables locales, évitant ainsi de nombreux maux de tête de portée qui peuvent se produire plus facilement dans Javascript vanilla.

Par exemple, le code Coffeescript suivant:

12345

$ -> $('#element').on 'click', -> state = 'clicked' window.state = 'clicked' console.log 'element clicked'

est converti en Javascript suivant:

1234567891011

(function() { $(function() { return $('#element').on('click', function() { var state; state = 'clicked'; window.state = 'clicked'; return console.log('element clicked'); }); });}).call(this);

Lorsque le préprocesseur traite le fichier, il encapsule automatiquement le code dans une fonction anonyme ((function() {}).call(this)) et ajoute le mot clé var à la première utilisation de state. Notez que si vous souhaitez utiliser la portée globale, vous devez la spécifier en préfixant window..

Il y a beaucoup plus à Coffeescript, mais la portée automatique m’a été extrêmement utile personnellement pour prévenir les bogues difficiles à trouver.

Assistants d’actifs Rails

Une autre fonctionnalité intéressante que vous ne pouvez obtenir qu’en utilisant Sass dans votre projet Rails est les assistants de chemin d’actifs. Lorsque vous référencez d’autres ressources dans votre Sass, vous pouvez utiliser la syntaxe suivante pour obtenir les chemins appropriés:

123

.logo { background-image: image-url("logo.png");}

Les aides image-path, asset-url et asset-path peuvent également être utilisées. Les assistants -url enveloppent le chemin avec url().

Erb dans les actifs

Le pipeline d’actifs vous permet d’évaluer le code erb dans vos actifs CSS et Javascript en suffixant le nom de fichier avec.erb (par exemple application.js.erb ou application.scss.erb). Bien que cela puisse être utile pour ajouter des chemins d’actifs à votre Javascript, dans l’ensemble, je ne recommande pas d’utiliser cette fonctionnalité. Il ajoute une autre étape de prétraitement au fichier, augmentant ainsi le temps de précompilation. Cela peut également conduire à de mauvaises habitudes. Vous pourriez être tenté d’ajouter du code qui n’a pas de sens au moment de la compilation, comme la traduction de chaînes. Ces chaînes ne seraient traduites qu’au moment de la compilation, annulant ainsi tout le but de les traduire. La seule raison d’utiliser Erb dans un fichier Javascript devrait être d’utiliser l’assistant asset_path comme indiqué dans le guide.

Pièges à pipeline d’actifs

Voici quelques pièges et petits trucs qui peuvent être utiles pour développer les actifs de votre application Rails.

• Comment ajouter des données globales à utiliser pour mon Javascript ?
  • La gemme gon peut être utilisée pour insérer des données de portée globale dans la page pour que votre Javascript puisse les consommer. C’est idéal pour des choses comme fournir l’ID de l’utilisateur actuel ou les paramètres du site.
• Où dois-je augmenter le tableau de précompilation?
  • Dans Rails 4, vous devez augmenter le tableau dans config/initializers/assets.rb, et dans Rails 3, vous devez le faire dans config/application.rb. Utilisation d’actifs.rb ou application.rb définit le tableau de précompilation pour tous les environnements de sorte que si vous ajoutez un environnement (peut-être staging), vous n’aurez pas besoin d’augmenter le tableau de précompilation spécifiquement pour ce nouvel environnement.
    • actifs.rb: Rails.application.config.assets.precompile += %w( widget.css widget.js )
    • demande.RB: config.assets.precompile += %w( widget.js widget.css )
• Quand dois-je précompiler les actifs séparément en augmentant le tableau de précompilation ?
  • Cela devrait rarement être fait. La plupart du temps, la seule raison pour laquelle vous voudriez le faire est si l’actif est inclus seul sur une page spéciale où vous ne voulez pas le reste des actifs, comme un widget intégré à une iframe. Utilisez votre application.js et application.manifestes css pour extraire vos actifs.
• Dois-je autoriser Rails à servir des fichiers statiques?
  • Oui. Cela suit les directives de l’application à douze facteurs et évite les erreurs si vous avez oublié d’inclure un fichier dans le tableau de précompilation ou si vous avez oublié de précompiler.
  • Place config.serve_static_assets = true dans les rails 3 et config.serve_static_files = true dans les rails 4.
• Comment puis-je m’assurer que mon Javascript / CSS est bien écrit ?
  • Écrire du Javascript et du CSS de haute qualité (ou du Coffeescript et du Sass) peut prendre beaucoup de temps et d’expérience, mais une chose qui m’a grandement aidé est d’utiliser un linter). CertainsEs, tels que Sublime Text, ont des plugins qui intègrent des linters. J’utilise personnellement le package SublimeLinter. Si vous allez écrire du Javascript et du CSS simples, vous devriez certainement utiliser un linter.
• Comment modifier le répertoire dans lequel mes actifs précompilés sont placés ?
  • Vous pouvez modifier le paramètre config.asset.prefix dans un autre répertoire, tel que /static.
  • Modifiez le préfixe de l’actif dans development.rb si vous souhaitez suivre les actifs précompilés dans git pour une utilisation en production.
  • Modifiez globalement le préfixe de l’actif si vous souhaitez utiliser l’espace de noms de chemin /assets pour vos contrôleurs.
• Comment servir des actifs statiques avec Nginx ?
  • La directive nginx de base devrait ressembler à ceci (voir la section des ressources de précompilation du guide Rails pour plus d’informations):

1234567

location ~ ^/assets/ { expires 1y; add_header Cache-Control public; add_header ETag ""; break;}

• Ce qui est manifeste.yml ou manifeste -.json ?
  • Le manifeste.yml (Rails 3) ou manifeste -.les fichiers json (Rails 4) sont créés automatiquement lorsque vous précompilez vos actifs avec rake assets:precompile. Ils contiennent des informations sur les fichiers à utiliser par votre application.
• Quels types de fichiers ne devraient PAS être inclus dans le pipeline d’actifs?
  • Vous voudrez généralement conserver des fichiers volumineux (vidéos, grand nombre de téléchargements PDF, etc.) dans un référentiel séparé ou dans un gestionnaire de fichiers cloud, tel qu’AWS S3. Les fichiers peuvent ensuite être référencés à partir de votre application, mais n’ont pas besoin de s’enliser dans votre référentiel git.
• Comment puis-je obtenir que mes ressources Rails 3 soient compilées plus rapidement?
  • Utilisez la gemme turbo-sprockets-rails3.
• Puis-je utiliser un CDN (réseau de diffusion de contenu) pour mes ressources ?
  • Oui! Le résumé, ou empreinte digitale, suffixé sur chaque actif les fait fonctionner parfaitement avec les CDN. Configurez votre CDN pour diffuser des ressources à partir de votre application Rails, puis définissez la configuration config.action_controller.asset_host sur le domaine approprié pour votre CDN (par exemple config.action_controller.asset_host = 'mycdn.fictional-cdn.com'). Je recommande d’utiliser des variables d’environnement pour définir ceci: config.action_controller.asset_host = ENV.

L’envelopper

L’utilisation correcte du pipeline d’actifs peut améliorer la qualité globale de votre application en termes de performances, de résilience et de propreté du code. En utilisant les fonctionnalités du pipeline d’actifs, vous pouvez résoudre automatiquement certains des problèmes les plus importants liés au codage et à la fourniture d’actifs statiques.