Rails 6: How to install css-bundling with Tailwind JIT

This tutorial explores how to install cssbundling-rails gem into existing rails applications with Webpacker.

• From a rails 6 app with legacy tailwindcss installed through Webpacker and a postcss.config.js file
• To the new cssbundling-rails gem and Tailwind JIT.

1. Install gem
2. Migrate config file
3. Migrate custom classes
4. Remove stylesheet_pack_tag
5. Remove or keep postcss file
6. Run the server with bin/dev
7. Github Actions
8. Heroku

In case you haven't heard about Tailwind JIT yet...

Tailwind JIT makes the development experience magnitudes faster. Only classes that are used in the application folder remain. Tailwind classes that you do not use are purged (removed) from your application.css file, significantly reducing the CSS file size and speeding up re-compiling CSS.

1. Install gem

Depending on how you initially installed tailwind, remove the original installed gem or package (tailwindcss).

• Add the gem to gemfile:

gem 'cssbundling-rails'

• Run in the terminal:

bundle install
rails css:install:tailwind

The install:tailwind command will do most of the heavy lifting of the migration:

• a /builds folder with an application.css where all your tailwindcss will compile
• a tailwind.config.js file in the root of the project

2. Migrate config file

Migrate the content from the legacy tailwind.config.js file inside the app/javascript/stylesheets folder to the newly created tailwind.config.js file at the app's top level. Make sure to active jit by adding in mode: 'jit'. After migrating the file's content, delete the original file.

// old
module.exports = {
  purge: [
    './app/**/*.html.erb',
    './app/helpers/**/*.rb',
    './app/javascript/**/*.js'
  ],
  variants: {
    extend: {
      opacity: ['disabled'],
    }
  },
  plugins: [
    require('@tailwindcss/forms'),
    require('@tailwindcss/typography'),
    require('@tailwindcss/aspect-ratio'),
  ]
}

// new
module.exports = {
  mode: 'jit',
  purge: [
    './app/views/**/*.html.erb',
    './app/helpers/**/*.rb',
    './app/javascript/**/*.js'
  ],
  plugins: [
    require('@tailwindcss/forms'),
    require('@tailwindcss/typography'),
    require('@tailwindcss/aspect-ratio'),
  ]
}

When using Tailwind JIT, variants are redundant. Just-in-time compiling enables us to create classes on the fly. You can delete custom variants completely. Read more about this cool JIT feature here.

3. Migrate custom classes

• Import Tailwind in app/assets/stylesheets/application.tailwind.css.

@tailwind base;
@tailwind components;
@tailwind utilities;

• Migrate the remaining content (any scss. or .css file) of the javascript/stylesheets folder to into the asset pipeline (app/assets/stylesheets).

After migrating, remove the stylesheets folder in app/javascript

4. Remove stylesheet_pack_tag

Webpacker refers to the location of a stylesheet using a stylesheet_pack_tag. As tailwindcss moves into the asset pipeline (app/assets/...), the stylesheet_pack_tag is no longer needed.

In your application.html.erb file (or any other layouts you render), remove the stylesheet_pack_tag. Note that the gem's install process automatically inserts the new stylesheet_link_tag refering to the asset pipeline.

<%# old %>
<%= stylesheet_pack_tag 'application', media: 'all', 'data-turbo-track': 'reload' %>

<%# new - automatically insert by cssbundling gem %>
<%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>

5. Remove or keep postcss file

You have 2 options here.

1. To use Tailwind without importing any relative files. Remove the postcss.config.js file at the root of your project. This is the most simple set-up.
2. To import relative files into Tailwind with the @import directive an additional package import-css is needed. Read Import Class in Relative File into Tailwind CSS and Rails for details on how to set it up.

6. Run the server with bin/dev

An important point. To benefit from Tailwind JIT's auto-recompiling, you need to have an additional watch process running. You can run a rails server in one terminal tab and yarn build:css --watch in another.

Or you can take full use of your appended Procfile.dev, which allows us to run both watch processes with a single command. Run ./bin/dev instead of ./bin/rails server.

7. Github Actions

If you use Github Actions as a CI/CD make sure to add in an additional build step. The application.tailwind.css file needs to be bundled before running the tests in your workflow file.

- name: Build TailwindCSS
  run: yarn build:css

8. Heroku

If you use heroku to deploy your application, Heroku will automatically pick up the additional build process build:css from your package.json file.

Thanks for reading.

Questions, feedback? Let me know.