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.

Installation

With Rails 7 you can generate a new application preconfigured with Tailwind 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 tailwind 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 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 v4 upgrade is out of scope for this README, so we strongly urge you to read the official Tailwind 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, however.

You don’t have to upgrade

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

Just make sure you’re either pinned to v3.3.1 of this gem:

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

or if you’re on an earlier version of this gem, 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"

Upgrade steps

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

Then, run the tailwindcss:upgrade task. 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 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.
  • Removes unnecessary stylesheet_link_tag "tailwindcss" tags from the application layout.
  • Removes references to the Inter font from the application layout.
  • Runs 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.

$ bin/rails tailwindcss:upgrade
       apply  /path/to/tailwindcss-rails/lib/install/upgrade_tailwindcss.rb
  Removing references to 'defaultTheme' from /home/user/myapp/config/tailwind.config.js
        gsub    config/tailwind.config.js
  Strip Inter font CSS from application layout
        gsub    app/views/layouts/application.html.erb
  Remove unnecessary stylesheet_link_tag from application layout
        gsub    app/views/layouts/application.html.erb
  Moving application.tailwind.css to /home/user/myapp/app/assets/tailwind
      create    app/assets/tailwind/application.tailwind.css
      remove    app/assets/stylesheets/application.tailwind.css
10.9.0
  Running the upstream Tailwind CSS upgrader
         run    npx @tailwindcss/upgrade@next --force --config /home/user/myapp/config/tailwind.config.js from "."
≈ tailwindcss v4.0.0
│ Searching for CSS files in the current directory and its subdirectories…
│ ↳ Linked `./config/tailwind.config.js` to `./app/assets/tailwind/application.tailwind.css`
│ Migrating JavaScript configuration files…
│ ↳ The configuration file at `./config/tailwind.config.js` could not be automatically migrated to the new CSS
│   configuration format, so your CSS has been updated to load your existing configuration file.
│ Migrating templates…
│ ↳ Migrated templates for configuration file: `./config/tailwind.config.js`
│ Migrating stylesheets…
│ ↳ Migrated stylesheet: `./app/assets/tailwind/application.tailwind.css`
│ ↳ No PostCSS config found, skipping migration.
│ Updating dependencies…
│ Could not detect a package manager. Please manually update `tailwindcss` to v4.
│ Verify the changes and commit them to your repository.
  Compile initial Tailwind build
         run    rails tailwindcss:build from "."
≈ tailwindcss v4.0.0
Done in 56ms
         run  bundle install --quiet

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!

Troubleshooting

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:

  • If the user isn’t using PostCSS, some migrations (e.g., updating class names in the view files) may fail
  • In setups without JavaScript tooling, the update process may fail to fully migrate tailwind.config.js because the tool assumes that the imported packages (e.g., tailwind plugins) are installed via a package manager, allowing them to be called.

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

Developing with Tailwindcss

Configuration and commands

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

The tailwindcss:install task will generate a Tailwind input file in app/assets/tailwind/application.tailwind.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 to app/assets/tailwind. 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:watch - start live rebuilds, generating output on file changes
    • bin/rails tailwindcss:watch[debug] - generate unminimized output
    • bin/rails tailwindcss:watch[poll] - for systems without file system events
    • bin/rails tailwindcss:watch[always] - for systems without TTY (e.g., some docker containers)

Note that you can combine task options, e.g. rails tailwindcss:watch[debug,poll].

This gem also makes available a Puma plugin to manage a live rebuild process when you run rails server (see “Live Rebuild” section below).

This gem also generates a Procfile.dev file which will run both the rails server and a live rebuild process (see “Live Rebuild” section below).

Building for production

The tailwindcss:build is automatically attached to assets:precompile, so before the asset pipeline digests the files, the Tailwind output will be generated.

Building for testing

The tailwindcss:build task is automatically attached to the test:prepare Rake task. This task runs before test commands. If you run bin/rails test in your CI environment, your Tailwind output will be generated before tests run.

Building unminified assets

If you want unminified assets, you can pass a debug argument to the rake task, i.e. rails tailwindcss:build[debug] or rails tailwindcss:watch[debug].

Live rebuild

While you’re developing your application, you want to run Tailwind in “watch” mode, so changes are automatically reflected in the generated CSS output. You can do this in a few different ways:

  • use this gem’s Puma plugin to integrate “watch” with rails server,
  • or run rails tailwindcss:watch as a separate process,
  • or run bin/dev which uses Foreman

Puma plugin

This gem ships with a Puma plugin. To use it, add this line to your puma.rb configuration:

plugin :tailwindcss if ENV.fetch("RAILS_ENV", "development") == "development"

and then running rails server (or just puma) will run the Tailwind watch process in the background.

Run rails tailwindcss:watch

This is a flexible command, which can be run with a few different options.

If you are running rails tailwindcss:watch on a system that doesn’t fully support file system events, pass a poll argument to the task to instruct tailwindcss to instead use polling:

rails tailwindcss:watch[poll]

(If you use bin/dev then you should modify your Procfile.dev to use the poll option.)

If you are running rails tailwindcss:watch as a process in a Docker container, set tty: true in docker-compose.yml for the appropriate container to keep the watch process running.

If you are running rails tailwindcss:watch in a docker container without a tty, pass the always argument to the task to instruct tailwindcss to keep the watcher alive even when stdin is closed: rails tailwindcss:watch[always]. If you use bin/dev then you should modify your Procfile.dev.

Foreman

Running bin/dev invokes Foreman to start both the Tailwind watch process and the rails server in development mode based on your Procfile.dev file.

Using with PostCSS

If you want to use PostCSS as a preprocessor, create a custom postcss.config.js in your project root directory, and that file will be loaded by tailwind automatically.

For example, to enable nesting:

// postcss.config.js
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  }
}

⚠ Note that PostCSS is a javascript tool with its own prerequisites! By default tailwindcss-rails does not require any javascript tooling, so in order to use PostCSS, a package.json with dependencies for your plugins and a package manager like yarn or npm is required, for example:

// package.json
{
  "name": "my app",
  "private": true,
  "dependencies": {
    "@tailwindcss/postcss": "^4.0.0",
    "tailwindcss": "^4.0.0",
    "postcss": "^8.5.1"
  }
}

Then you can use yarn or npm to install the dependencies.

Custom inputs or outputs

If you need to use a custom input or output file, you can run bundle exec tailwindcss to access the platform-specific executable, and give it your own build options.

Troubleshooting

Some common problems experienced by users …

Lost keystrokes or hanging when using terminal-based debugging tools (e.g. IRB, Pry, ruby/debug…etc.) with the Puma plugin

We’ve addressed the issue and you can avoid the problem by upgrading tailwindcss-rails to v2.4.1 or later versions.

Running in a docker container exits prematurely

If you are running rails tailwindcss:watch as a process in a Docker container, set tty: true in docker-compose.yml for the appropriate container to keep the watch process running.

If you are running rails tailwindcss:watch in a docker container without a tty, pass the always argument to the task to instruct tailwindcss to keep the watcher alive even when stdin is closed: rails tailwindcss:watch[always]. If you use bin/dev then you should modify your Procfile.dev.

Conflict with sassc-rails

Tailwind uses modern CSS features that are not recognized by the sassc-rails extension that was included by default in the Gemfile for Rails 6. In order to avoid any errors like SassC::SyntaxError, you must remove that gem from your Gemfile.

Class names must be spelled out

For Tailwind to work, your class names need to be spelled out. If you need to make sure Tailwind generates class names that don’t exist in your content files or that are programmatically composed, use the safelist option.

ERROR: Cannot find the tailwindcss executable for supported platform

See https://github.com/flavorjones/tailwindcss-ruby for help.

Using asset-pipeline assets

In Rails, you want to use assets from the asset pipeline to get fingerprinting. However, Tailwind isn’t aware of those assets.

To use assets from the pipeline, use url(image.svg). Since Sprockets v3.3.0 url(image.svg) is rewritten to /path/to/assets/image-7801e7538c6f1cc57aa75a5876ab0cac.svg so output CSS will have the correct path to those assets.

module.exports = {
    theme: {
        extend: {
            backgroundImage: {
                'image': "url('image.svg')"
            }
        }
    }
}

The inline version also works:

Has the image as it's background

License

Tailwind for Rails is released under the MIT License.
The Inter font is released under the SIL Open Font License, Version 1.1.