tailwindcss-rails

Tailwind CSS for Rails

Tailwind CSS is a utility-first CSS framework packed with classes like flex, pt-4, text-center and rotate-90 that can be composed to build any design, directly in your markup.

[!NOTE] This document is specific to Tailwind v4, corresponding to v4 of this gem. If you are looking for documentation for v3, please visit to the tailwindcss-rails v3 README.

• Installation
  • Choosing a specific version of tailwindcss
  • Using a local installation of tailwindcss
• Upgrading your application from Tailwind v3 to v4
  • You don't have to upgrade
  • Upgrade steps
  • Troubleshooting a v4 upgrade
  • Updating CSS class names for v4
• Developing with TailwindCSS
  • Configuration and commands
  • Building for production
  • Building for testing
  • Building unminified assets
  • Live rebuild
  • Using Tailwind plugins
  • Using with PostCSS
  • Custom inputs or outputs
  • Rails Engines support (Experimental)
• Troubleshooting
  • The watch command is hanging
  • The build command (or bin/rails assets:precompile) is hanging inside a docker container
  • Lost keystrokes or hanging when using terminal-based debugging tools (e.g. IRB, Pry, ruby/debug...etc.) with the Puma plugin
  • Running in a docker container exits prematurely
  • Conflict with sassc-rails
  • Class names must be spelled out
  • ERROR: Cannot find the tailwindcss executable for supported platform
  • Using asset-pipeline assets
• License

Installation

With Rails 7 you can generate a new application preconfigured with Tailwind CSS by using --css tailwind. If you're adding Tailwind later, you need to:

1. Run ./bin/bundle add tailwindcss-rails
2. Run ./bin/rails tailwindcss:install

This gem depends on the tailwindcss-ruby gem to install a working TailwindCSS CLI executable.

Choosing a specific version of tailwindcss

The tailwindcss-ruby gem is declared as a floating dependency of this gem, so by default you will get the most recent stable version. However, you can select a specific version of Tailwind CSS by pinning that gem to the analogous version in your application's Gemfile. For example,

gem "tailwindcss-rails"

# pin to tailwindcss version 3.4.13
gem "tailwindcss-ruby", "3.4.13"

Using a local installation of tailwindcss

You can also use a local (npm-based) installation if you prefer, please go to https://github.com/flavorjones/tailwindcss-ruby for more information.

Upgrading your application from Tailwind v3 to v4

v4.x of this gem has been updated to work with Tailwind v4, including providing some help with upgrading your application.

A full explanation of a Tailwind CSS v4 upgrade is out of scope for this README, so we strongly urge you to read the official Tailwind CSS v4 upgrade guide before embarking on an upgrade to an existing large app.

This gem will help with some of the mechanics of the upgrade:

• update some generated files to handle breaking changes in v4 of this gem,
• update some local project files to meet some Tailwind CSS v4 conventions,
• attempt to run the upstream v4 upgrade tool.

You don't have to upgrade

Keep in mind that you don't need to upgrade. You can stay on Tailwind CSS v3 for the foreseeable future if you prefer not to migrate now, or if your migration runs into problems.

If you don't want to upgrade, then pin your application to v3.3.1 of this gem:

# Gemfile
gem "tailwindcss-rails", "~> 3.3.1" # which transitively pins tailwindcss-ruby to v3

If you're on an earlier version of this gem, <= 3.3.0, then make sure you're pinning the version of both tailwindcss-rails and tailwindcss-ruby:

# Gemfile
gem "tailwindcss-rails", "~> 3.3"
gem "tailwindcss-ruby", "~> 3.4" # only necessary with tailwindcss-rails <= 3.3.0

Upgrade steps

[!WARNING] In applications using Tailwind plugins without JavaScript tooling, these upgrade steps may fail to fully migrate tailwind.config.js because the upstream upgrade tool needs the Tailwind plugins to be installed and available through a JavaScript package manager. If you see errors from the upstream upgrade tool, you should try following the additional steps in Updating CSS class names for v4 which will help you install (temporarily!) the necessary packages and clean up afterwards.

First, update to tailwindcss-rails v4.0.0 or higher. This will also ensure you're transitively depending on tailwindcss-ruby v4.

# Gemfile 
gem "tailwindcss-rails", "~> 4.0" # which transitively pins tailwindcss-ruby to v4

Update path references to any existing css files imported in app/assets/stylesheets/application.tailwind.css so that they will resolve when the file is moved to app/assets/tailwind/application.css.

-@import "pagy.css";
+@import "../stylesheets/pagy.css";

If you want to migrate CSS class names for v4 (this is an optional step!), jump to Updating CSS class names for v4 before continuing.

Then, run bin/rails tailwindcss:upgrade. Among other things, this will try to run the official Tailwind upgrade utility. It requires npx in order to run, but it's a one-time operation and is highly recommended for a successful upgrade.

Here's a detailed list of what the upgrade task does.

• Cleans up some things in the generated config/tailwind.config.js.
• If present, moves config/postcss.config.js to the root directory.
• If present, moves app/assets/stylesheets/application.tailwind.css to app/assets/tailwind/application.css.
• Removes unnecessary stylesheet_link_tag "tailwindcss" tags from the application layout.
• Removes references to the Inter font from the application layout.
• Runs v4.1.4 of the upstream upgrader (note: requires npx to run the one-time upgrade, but highly recommended).

Here's what that upgrade looks like on a vanilla Rails app.

…

If this doesn't succeed, it's likely that you've customized your Tailwind configuration and you'll need to do some work to make sure your application upgrades. Please read the official upgrade guide and try following the additional steps in Updating CSS class names for v4.

Troubleshooting a v4 upgrade

You may want to check out TailwindCSS v4 - upgrade experience report · rails/tailwindcss-rails · Discussion #450 if you're having trouble upgrading.

We know there are some cases we haven't addressed with the upgrade task:

• In applications using Tailwind plugins without JavaScript tooling, these upgrade steps may fail to fully migrate tailwind.config.js because the upstream upgrade tool needs the Tailwind plugins to be installed and available through a JavaScript package manager. If you see errors from the upstream upgrade tool, you should try following the additional steps in Updating CSS class names for v4 which will help you install (temporarily!) the necessary packages and clean up afterwards.

We'll try to improve the upgrade process over time, but for now you may need to do some manual work to upgrade.

Updating CSS class names for v4

[!NOTE] If you'd like to help automate these steps, please drop a note to the maintainers in this discussion thread.

With some additional manual work the upstream upgrade tool will update your application's CSS class names to v4 conventions. This is an optional step that requires a JavaScript toolchain.

Add the following line to the .gitignore file, to prevent the upstream upgrade tool from accessing node_modules files.

/node_modules

Create or update a package.json in the root of the project:

{
  "name": "app_name",
  "version": "1.0.0",
  "dependencies": {
    "tailwindcss": "^3.4.17", // Mandatory!!
    // Install all plugins and modules that are referenced in tailwind.config.js
    "@tailwindcss/aspect-ratio": "^0.4.2",
    "@tailwindcss/container-queries": "^0.1.1",
    "@tailwindcss/forms": "^0.5.10",
    "@tailwindcss/typography": "^0.5.16",
    // And so on...
  },
}

Run npm install (or yarn install if using yarn)

Update config/tailwind.config.js and temporarily change the content part to have an additional . on all paths so they are relative to the config file:

  content: [
    '../public/*.html',
    '../app/helpers/**/*.rb',
    '../app/javascript/**/*.js',
    '../app/views/**/*.{erb,haml,html,slim}'
  ],

(Just add an additional . to all the paths referenced)

Run the upstream upgrader as instructed above.

Then, once you've run that successfully, clean up:

• Review package.json to remove unnecessary modules.
  • This includes modules added for the period of upgrade.
  • If you don't need any modules besides tailwindcss itself, delete package.json, node_modules/ and package-lock.json (or yarn.lock), plus remove /node_modules from .gitignore.
• Go to your CSS file and remove the following line (if present):

  @plugin '@tailwindcss/container-queries';
  

• Revert the changes to config/tailwind.config.js so that paths are once again relative to the application root.

Developing with TailwindCSS

Configuration and commands

Input file: app/assets/tailwind/application.css

The tailwindcss:install task will generate a Tailwind input file in app/assets/tailwind/application.css. This is where you import the plugins you want to use and where you can setup your custom @apply rules.

⚠ The location of this file changed in v4, from app/assets/stylesheets/application.tailwind.css to app/assets/tailwind/application.css. The tailwindcss:upgrade task will move it for you.

Output file: app/assets/builds/tailwind.css

When you run rails tailwindcss:build, the input file will be used to generate the output in app/assets/builds/tailwind.css. That's the output CSS that you'll include in your app.

Commands

This gem makes several Rails tasks available, some of which have multiple options which can be combined.

Synopsis:

• bin/rails tailwindcss:install - installs the configuration file, output file, and Procfile.dev
• bin/rails tailwindcss:build - generate the output file
  • bin/rails tailwindcss:build[debug] - generate unminimized output
  • bin/rails tailwindcss:build[silent] - suppress non-error output from