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
- To the new
cssbundling-railsgem and Tailwind JIT.
- Install gem
- Migrate config file
- Migrate custom classes
- Remove stylesheet_pack_tag
- Remove or keep postcss file
- Run the server with bin/dev
- Github Actions
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.
Depending on how you initially installed tailwind, remove the original installed gem or package (
- Add the gem to gemfile:
- Run in the terminal:
bundle install rails css:install:tailwind
install:tailwind command will do most of the heavy lifting of the migration:
/buildsfolder with an
application.csswhere all your tailwindcss will compile
- a tailwind.config.js file in the root of the project
Migrate the content from the legacy tailwind.config.js file inside the
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.
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.
- Import Tailwind in
@tailwind base; @tailwind components; @tailwind utilities;
- Migrate the remaining content (any scss. or .css file) of the
After migrating, remove the stylesheets folder in
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.
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" %>
You have 2 options here.
- To use Tailwind without importing any relative files. Remove the
postcss.config.jsfile at the root of your project. This is the most simple set-up.
- To import relative files into Tailwind with the @import directive an additional package
import-cssis needed. Read Import Class in Relative File into Tailwind CSS and Rails for details on how to set it up.
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
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
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.