Tailwind CSS for Rails

  • By Ruby on Rails
  • Last update: Dec 1, 2022
  • Comments: 16

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.

This gem wraps the standalone executable version of the Tailwind CSS 3 framework. These executables are platform specific, so there are actually separate underlying gems per platform, but the correct gem will automatically be picked for your platform. Supported platforms are Linux x64, macOS arm64, macOS x64, and Windows x64. (Note that due to this setup, you must install the actual gems – you can't pin your gem to the github repo.)

You can customize the Tailwind build through the config/tailwind.config.js file, just like you would if Tailwind was running in a traditional node installation. All the first-party plugins are supported.

The installer will create your Tailwind input file in app/assets/stylesheets/application.tailwind.css. This is where you import the plugins you want to use, and where you can setup your custom @apply rules. When you run rails tailwindcss:build, this 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 (the installer automatically configures this, alongside the Inter font as well).

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.

When 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 either by running rails tailwindcss:watch as a separate process, or by running ./bin/dev which uses foreman to starts both the Tailwind watch process and the rails server in development mode.


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

Building in production

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

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.


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




  • 1

    Heroku Issue: ActionView::Template::Error (The asset "tailwind.css" is not present in the asset pipeline.")


    Thanks for your work.

    I'm running a very simple Rails which I've just set up.

    Everything is working swimmingly locally, but when I deploy to heroku I'm getting the following error when I try to view a page:

    ActionView::Template::Error (The asset "tailwind.css" is not present in the asset pipeline.)

    I have checked to ensure that sassc-rails is disabled in the Gemfile.

    I have also tried adding

    config.assets.css_compressor = nil

    to production.rb, but the error remains.

    Any ideas where I am going wrong?


  • 2

    fix: ship an x86_64-linux-musl platform gem

    This was not strictly necessary before now because musl platforms have always used the generic platform gem, but recent changes in rubygems and bundler introduced new behaviors around libc flavors, and so we're going the extra mile here to be explicit.

    See #192 for context, also see https://github.com/rubygems/rubygems/pull/5875

  • 3

    Multiple CSS files for Tailwind apply directives


    We have used tailwind for some time in our project and are now attempting to upgrade to Rails 7 with importmaps and this gem instead of Node. We seem to have stumbled upon a problem with how we arranged our CSS files as we had split them over multiple files and done @import in our application.css file. If we do that with this gem we just get these errors screenshot

    The CSS will start working again if we merge all into the application.tailwind.css but that results in a large and unwieldy file. So the main question is: Is there a way to have multiple CSS files that are compiled by tailwind without using Node

  • 4

    Support for arm64-darwin-21

    Steps to reproduce

    1. Make sure to run these commands on a M1 Pro machine
    2. Run ./bin/bundle add tailwindcss-rails
    3. Run ./bin/rails tailwindcss:install


    Tailwind is correctly installed in the app


    The following error is displayed:

    ERROR: Cannot find the tailwindcss executable for arm64-darwin-21 in ~/.gem/ruby/3.0.3/gems/tailwindcss-rails-2.0.2/exe
    If you're using bundler, please make sure you're on the latest bundler version:
      gem install bundler
      bundle update --bundler
    Then make sure your lock file includes this platform by running:
      bundle lock --add-platform arm64-darwin-21
      bundle install
    See `bundle lock --help` output for details.


    Apple's M1 Pro chip is referenced as arm64-darwin-21. So the installation process can't succeed because the executable file is missing for the platform.

    In order to test this, I did the following:

    1. Cloned the repo,
    2. Updated the NATIVE_PLATOFORMS constant
    3. Ran rake gem:arm64-darwin-21
    4. Copied the newly generated folder from the gem's repo ./exe/arm64-darwin-21 to the gem's folder in my machine ~/.gem/ruby/3.0.3/gems/tailwindcss-rails-2.0.2/exe/arm64-darwin-21
    5. Ran the ./bin/rails tailwindcss:install command and everything worked successfully
    6. Tailwind was properly installed

    Perhaps we could update the package.rake to alias arm64-darwin to arm64-darwin-21 or something similar. Perhaps this will make more sense if it becomes a trend for Apple to change their processor's arch name after a new release. I'm still unsure if the M1 Max has a different name, I'd bet it does.

  • 5

    tailwindcss-rails raising SassC::SyntaxError

    I am using gem 'tailwindcss-rails'


        <%= stylesheet_link_tag "inter-font", "data-turbo-track": "reload" %>
        <%= stylesheet_link_tag "tailwind", "data-turbo-track": "reload" %>

    Production: config.assets.css_compressor = :purger

    In circle ci it's raising a following error

    rake aborted! SassC::SyntaxError: Error: unterminated attribute selector for type on line 1021:16 of stdin

    .prose ol[type="A" s] {

    ---------------^ stdin:1021

  • 6

    Tailwind.config.js with asset pipeline

    Thanks for providing this gem.

    I can't seem to find documentation on how to customize Tailwind when using the asset pipeline. I have a tailwind.config.js file in my rails root directory. Do I need to move the file to assets/javascripts/?

    What's the proper way to do this?

  • 7

    Provide all first party plugins for the bundled Tailwind CSS

    Hey everyone 👋

    I was wondering if there was a reason to not include all of the first party plugins for the bundled tailwind.css. From what I can tell, these are the first party plugins that are not yet bundled:

    • [ ] Active
    • [ ] Group-focus
    • [ ] Motion-safe
    • [ ] Motion-reduce
    • [ ] Disable
    • [ ] Visited
    • [ ] Checked
    • [ ] First-child
    • [ ] Last-child
    • [ ] Odd-child
    • [ ] Even-child

    I'm working on a new project without webpacker, and with these plugins, I can't think of anything else that would be missing.


  • 8

    Some tailwind styles not working out of the box in rails 7

    I have noticed that several tailwind styles are not working out of the box in rails 7. I have been using tailwindui components in a rails 6 project and in the process of upgrading to rails 7 seem to notice many of my styles are broken. Am I doing something wrong? This repository has an example, you can see the shadow class doesn't seem to apply, though many of the layout classes seem to work ok:


  • 9

    how to install on M1 (running in a container)

    Let me start by apologizing for 'fuming in the wrong kitchen' (this is not tailwindcss-rails per se - I actually anticipate it doing exactly what it should! It's much more likely some Docker container "thing" that lures the container into reporting "aarch64-linux" which I -- by now -- have learned repeatedly, is not a supported architecture by tailwindcss-rails !

    Reckoning me not being alone on this crusade I risk the barrage and go forth:

    Question: Does anyone know how to get Rails 7.0.0 to install with TailwindCSS in containers on the Apple M1 ?

    the sordid details

    Apple's latest/finest 'sand' - the M1 - is screaming fast but somewhat of a challenge to run Docker containers on;

    Like with the sparkling fresh Rails 7.0.0 when doing rails new . --css=tailwind

    I have a Dockerfile like this

    [ update: 2021-12-20 22:30 CEST: the from image is actually arm64v8/ruby ]

    FROM arm64v8/ruby:3.03
    # I took great inspiration in this work by [Will Schenk](https://willschenk.com/articles/2020/rails_in_docker/)
    WORKDIR /app
    COPY src/Gemfile /app/Gemfile
    COPY src/Gemfile.lock /app/Gemfile.lock
    RUN gem install bundler && bundle install
    # Add a script to be executed every time the container starts.
    COPY entrypoint.sh /usr/bin/
    RUN chmod +x /usr/bin/entrypoint.sh
    ENTRYPOINT ["entrypoint.sh"]
    EXPOSE 3000
    # Configure the main process to run when running the image
    CMD ["rails","server","-b",""]

    and a docker-compose.yml like this (the db part is merely for completeness - it serves no purpose in this trickery

    # Most if not all of it is a blatant c/p from
    # Will Schenk's https://willschenk.com/articles/2020/rails_in_docker/
    version: "3.9"
        build: mysql 
        platform: linux/x86_64
        image: mindling_db
        container_name: mindling_db
        command: [ "--default-authentication-plugin=mysql_native_password" ]
          - "3306:3306"
          - ~/src/mysql_data:/var/lib/mysql
          MYSQL_ROOT_PASSWORD: secret
          MYSQL_DATABASE: mindling_development
        platform: linux/arm64/v8
        build: .
        command: bash -c "rm -f tmp/pids/server.pid && bundle exec rails s -p 3000 -b ''"
          - ./src:/app
          - "3000:3000"
          - db

    When I let it 'rip' -- hoping to install tailwindcss goodness after the fact (it failed during the initial rails new too ) -- I get this sad reply:

    √ mindling % x rails tailwindcss:install
    Creating mindling_mindling_run ... done
    Add Tailwindcss include tags and container element in application layout
    File unchanged! The supplied flag value not found!  app/views/layouts/application.html.erb
    File unchanged! The supplied flag value not found!  app/views/layouts/application.html.erb
    File unchanged! The supplied flag value not found!  app/views/layouts/application.html.erb
    Build into app/assets/builds
           exist  app/assets/builds
       identical  app/assets/builds/.keep
    File unchanged! The supplied flag value not found!  app/assets/config/manifest.js
    File unchanged! The supplied flag value not found!  .gitignore
    File unchanged! The supplied flag value not found!  Procfile.dev
    Add bin/dev to start foreman
       identical  bin/dev
    Compile initial Tailwind build
             run  rails tailwindcss:build from "."
    ERROR: tailwindcss-rails does not support the aarch64-linux platform
    Please install tailwindcss following instructions at https://tailwindcss.com/docs/installation

    but for some reason the container keeps 'bragging about being' aarch64-linux 😆

    So - now my heading (and my bearing for that matter too) is somewhat lost!

    How do I get my containers to swallow their (linux) pride and start behaving?

  • 10

    Doesn't work on macOS (M1)

    Hello, I have created new rails app with --css tailwind flag. Neither rails tailwindcss:build nor rails tailwindcss:watch produce any output and fail silently. TailwindCSS executable doesn't seem to be installed with gem.

    In my case command that is executed under the hood looks like this: /Users/user/.rbenv/versions/3.0.3/lib/ruby/gems/3.0.0/gems/tailwindcss-rails-2.0.0/lib/tasks/../../exe/tailwindcss -i /Users/user/project/app/assets/stylesheets/application.tailwind.css -o /Users/user/project/app/assets/builds/tailwind.css -c /Users/user/project/config/tailwind.config.js

    And when I try to execute it manually I get: zsh: no such file or directory: /Users/user/.rbenv/versions/3.0.3/lib/ruby/gems/3.0.0/gems/tailwindcss-rails-2.0.0/lib/tasks/../../exe/tailwindcss

  • 11

    Package the `tailwindcss` binary executable

    This is an exploration of how we could package and redistribute the binaries from https://github.com/tailwindlabs/tailwindcss/releases with this gem.


    The general approach followed here is to create a new gem file for each of the native binary platforms supported upstream:

    • x86_64-linux
    • x86_64-darwin
    • x64-mingw32
    • arm64-darwin

    in addition to the vanilla ruby gem which is unchanged by this PR. In each of those "native" gems, there will be two additional files:

    • exe/<platform>/tailwindcss, the binary executable downloaded from tailwindlabs/tailwindcss (note the rename from upstream release)
    • exe/tailwindcss, a generic ruby script to find and run the binary

    Note that the exe/tailwindcss script is required because rubygems requires that executables declared in a gemspec must be Ruby scripts (and we must declare an executable in order to hook into the user's shell $PATH).

    Also note that the final gem sizes are much larger because of the size of the tailwind executable:

    $ ls -glSr pkg/*gem
    -rw-rw-r-- 1 flavorjones  1063424 2021-12-16 01:05 pkg/tailwindcss-rails-1.0.0.gem
    -rw-rw-r-- 1 flavorjones 16760832 2021-12-16 01:06 pkg/tailwindcss-rails-1.0.0-x64-mingw32.gem
    -rw-rw-r-- 1 flavorjones 18651136 2021-12-16 01:06 pkg/tailwindcss-rails-1.0.0-x86_64-darwin.gem
    -rw-rw-r-- 1 flavorjones 19821056 2021-12-16 00:47 pkg/tailwindcss-rails-1.0.0-x86_64-linux.gem
    -rw-rw-r-- 1 flavorjones 20329472 2021-12-16 01:05 pkg/tailwindcss-rails-1.0.0-arm64-darwin.gem


    I've added a github actions pipeline to verify the executables work as desired on Linux, MacOS, and Windows.

    Some questions to consider

    What is the desired user experience for people not on one of the platforms published by tailwindcss?

    • This would include BSD users, ARM64 Linux users (Graviton), JRuby users, and 32-bit anything users.
    • Right now the tailwindcss executable will simply not be present, which may be confusing.
    • But shipping a tailwindcss script to notify the user may shadow the real executable when the user installs it, which may be even more confusing.

    What license or copyright declarations should be made in this project regarding redistributing tailwindcss?

    • One approach I've seen (and which I use in Nokogiri) is to create a separate file LICENSE-DEPENDENCIES which lists the libraries being redistributed.
    • This PR takes that approach, and includes that file in the native gems, but I'm open to other opinions.

    What should the process be to update to a newer version of the binaries?

    • In rakelib/package.rake there's a constant that can be manually updated, is that fine?
    • Should the "update tailwind" github action pipeline do something here?

    The binary isn't going to be available to anyone who's bundling using a git URL.

    • If that's a problem, we can solve it a few different ways ...
    • We could check in the binaries to the repo (but I'm not a huge fan of using git to store large opaque blobs)
    • We could have the exe/tailwindcss script download the binary if it's not available
      • This is basically the approach outlined in the next section

    Alternative approaches you might consider instead

    • use a shim that will download the binary executable on demand (similar to how https://github.com/flavorjones/chromedriver-helper used to work).
      • pro: no need for multiple gems, no need for large gem files
      • pro: no need to ship new gems if a new upstream version drops
      • con: challenging to create a reproducible development environment
      • con: users are on their own to choose to update or forget to update, and we may know better
  • 12

    feat: fall back to locally-installed tailwindcss executables

    If a user has installed the ruby platform gem, but has the tailwindcss executable installed in their path, then we should fall back to that.

    Closes #224

  • 13

    Pointing to the tailwindcss executable

    I'm running NixOs and due to multiple reasons I cannot install platform-native gems. However, I can install the tailwindcss executable on its own. However, this gem does not try checking PATH if the included version does not exist.

    I understand that this is probably for easier maintenance and is a good idea. However, could a configuration/escape hatch be added that would allow me to point it at the tailwindcss executable? The onus would be on me to make sure the versions match up etc...

    This would make it possible to use on NixOS while still keeping the niceties of the gem.

  • 14

    Help with gem development

    Hi there, I forked the repo (I am trying to add a postcss argument to the executable), but was unable to test it locally ( I keep on getting the error message

    Tailwindcss::Commands::ExecutableNotFoundException: Cannot find the tailwindcss executable for x86_64-linux in 
    If you're using bundler, please make sure you're on the latest bundler version:

    when I point my Gemfile either to my local path or to my github repo (

    gem 'tailwindcss-rails', '~> 2.0.17' # ok
    # gem 'tailwindcss-rails', path: '/home/murilo/code/learn/'  # raises error 
    # gem 'tailwindcss-rails', github: 'muriloime/tailwindcss-rails'  # raises error

    Could you please give instructions on how to test the gem locally or give some orientation on how to circumvent the error ?

    Many thanks

  • 15

    bin/rails tailwindcss:watch not triggering rebuild

    Bug report

    Steps to reproduce

    • Install or update to tailwindcss-rails v2.0.15 (also happens with current latest, v2.0.16)
    • run either bin/dev or bin/rails server and bin/rails tailwindcss:watch on separate terminals.

    Expected behavior

    Tailwind CSS should rebuild stylesheet after every change in files matching any tailwind.config.js module.exports.content patterns.

    Actual behavior

    Changes are ignored.

    System configuration

    Rails version: 7.0.4

    Ruby version: 3.1.2p20

  • 16

    Error: "wrong number of arguments (given 3, expected 1)" after install


    I installed on

    • Rails 7.0.1
    • Ruby Ruby 3.0.0

    Using these command: bundle add tailwindcss-rails rails tailwindcss:install

    And it shows this error on my rails app:

    Screen Shot 2022-09-29 at 16 49 18

    I installed 2 times and restarted the server several times and the same error keeps going.