Only load the CSS you need for the initial viewport in Rails!
This gem give you the ability to load only the CSS you need on an initial page view. This gives you blazin' fast rending as there's no initial network call to grab your application's CSS.
This gem assumes that you'll load the rest of the CSS asyncronously. At the moment, the suggested way is to use the loadcss-rails gem.
This gem uses Penthouse to generate the critical CSS.
Upgrading to the Latest Release
Upgrade instructions from each version are included below.
Installation
Add critical-path-css-rails
to your Gemfile:
gem 'critical-path-css-rails', '~> 1.0.1'
Download and install by running:
bundle install
Run the generator to install the rake task and configuration file:
rails generate critical_path_css:install
The generator adds the following files:
config/critical_path_css.yml
Note: This file supports ERB.lib/tasks/critical_path_css.rake
Usage
First, you'll need to configue a few things in the YAML file: config/critical_path_css.yml
manifest_name
: If you're using the asset pipeline, add the manifest name.css_path
: If you're not using the asset pipeline, you'll need to define the path to the application's main CSS. The gem assumes your CSS lives inRAILS_ROOT/public
. If your main CSS file is inRAILS_ROOT/public/assets/main.css
, you would set the variable to/assets/main.css
.routes
: List the routes that you would like to generate the critical CSS for. (i.e. /resources, /resources/show/1, etc.)base_url
: Add your application's URL for the necessary environments.
Before generating the CSS, ensure that your application is running (viewable from a browser) and the main CSS file exists. Then in a separate tab, run the rake task to generate the critical CSS.
If you are using the Asset Pipeline, precompiling the assets will generate the critical CSS after the assets are precompiled.
rake assets:precompile
Else you can generate the critical CSS manually using the below task:
rake critical_path_css:generate
To load the generated critical CSS into your layout, in the head tag, insert:
<style>
<%= CriticalPathCss.fetch(request.path) %>
</style>
A simple example using loadcss-rails looks like:
<style>
<%= CriticalPathCss.fetch(request.path) %>
</style>
<script>
loadCSS("<%= stylesheet_path('application') %>");
</script>
<link rel="preload" href="<%= stylesheet_path('application') %>" as="style" onload="this.rel='stylesheet'">
<noscript>
<link rel="stylesheet" href="<%= stylesheet_path('application') %>">
</noscript>
Route-level Control of CSS Generation and Removal
CriticalPathCss exposes some methods to give the user more control over the generation of Critical CSS and managment of the CSS cache:
CriticalPathCss.generate route # Generates the critical path CSS for the given route (relative path)
CriticalPathCss.generate_all # Generates critical CSS for all routes in critical_path_css.yml
CriticalPathCss.clear route # Removes the CSS for the given route from the cache
CriticalPathCss.clear_matched routes # Removes the CSS for the matched routes from the cache
NOTE: The clear_matched
method will not work with Memcached due to the latter's incompatibility with Rails' delete_matched
method. We recommend using an alternative cache such as Redis.
In addition to the critical_path_css:generate
rake task described above, you also have access to task which clears the CSS cache:
rake critical_path_css:clear_all
NOTE: The critical_path_css:clear_all
rake task may need to be customized to suit your particular cache implementation.
Careful use of these methods allows the developer to generate critical path CSS dynamically within the app. The user should strongly consider using a background job when generating CSS in order to avoid tying up a rails thread. The generate
method will send a GET request to your server which could cause infinite recursion if the developer is not careful.
A user can use these methods to dynamically generate critical path CSS without using the rake critical_path_css:generate
rake task and without hardcoding the application's routes into config/critical_path_css.yml
. See this Gist for an example of such an implementation.
Upgrading from version 0.X.X to 1.0.0
To maintain the latest version of Penthouse, this gem now depends on NodeJS and NVM to be installed on the system.
Upgrading from a version earlier than 0.3.0
The latest version of Critcal Path CSS Rails changes the functionality of the generate
method. In past versions,
generate
would produce CSS for all of the routes listed in config/critical_path_css.yml
. This functionality has been replaced by the generate_all
method, and generate
will only produce CSS for one route.
Developers upgrading from versions prior to 0.3.0 will need to replace CriticalPathCss:generate
with CriticalPathCss:generate_all
throughout their codebase. One file that will need updating is lib/tasks/critical_path_css.rake
. Users can upgrade this file automatically by running:
rails generate critical_path_css:install
Answer 'Y' when prompted to overwrite critical_path_css.rake
. However, overwriting critical_path_css.yml
is not necessary and not recommended.
Versions
The critical-path-css-rails gem follows these version guidelines:
patch version bump = updates to critical-path-css-rails and patch-level updates to Penthouse
minor version bump = minor-level updates to critical-path-css-rails and Penthouse
major version bump = major-level updates to critical-path-css-rails, Penthouse, and updates to Rails which may be backwards-incompatible
Contributing
Feel free to open an issue ticket if you find something that could be improved. A couple notes:
- If the Penthouse.js script is outdated (i.e. maybe a new version of Penthouse.js was released yesterday), feel free to open an issue and prod us to get that thing updated. However, for security reasons, we won't be accepting pull requests with updated Penthouse.js script.
Copyright Mudbug Media and Michael Misshore, released under the MIT License.