tailwindcss-rails

Tailwind CSS for Rails uses an input file to define custom @apply rules and plugin imports, which is then compiled into an output CSS file for your application.

• Input file: app/assets/tailwind/application.css. This is where you import plugins and set up custom styles. (Note: In v4, this moved from app/assets/stylesheets/application.tailwind.css).
• Output file: app/assets/builds/tailwind.css. This is the generated file that you should include in your application's layout.

If you are developing a Rails Engine that uses Tailwind, you can provide an engine-specific CSS file at app/assets/tailwind/<engine_name>/engine.css.

On the first build or manual call to rails tailwindcss:engines, entry point files will be created in app/assets/builds/tailwind/<engine_name>.css.

Important: You must manually opt-in to including the engine's CSS by adding an @import statement to your host application's app/assets/tailwind/application.css:

@import "../builds/tailwind/<engine_name>";

If you do not wish to upgrade to Tailwind v4, you can pin your application to version 3 of the gem.

For modern versions of the gem, pin to ~> 3.3.1 to transitively pin tailwindcss-ruby to v3.

If you are using an older version of the gem (<= 3.3.0), you must pin both tailwindcss-rails and tailwindcss-ruby explicitly in your Gemfile.

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

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

To generate unminified CSS for easier debugging, you can use either a Rake task argument or an environment variable:

1. Pass the debug argument: rails tailwindcss:build[debug] or rails tailwindcss:watch[debug].
2. Set the TAILWINDCSS_DEBUG environment variable to any non-blank value.

If both are provided, the TAILWINDCSS_DEBUG environment variable takes precedence.

To have Tailwind CSS automatically rebuild when you change files, use one of these three methods:

1. Puma Plugin (Recommended for rails server)

Add the following to your config/puma.rb to run the watch process in the background whenever you start the server in development:

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

2. Separate Process

Run the watch command in a dedicated terminal window:

bin/rails tailwindcss:watch

3. Foreman (bin/dev)

Run bin/dev, which uses the Procfile.dev generated during installation to start both the Rails server and the Tailwind watch process simultaneously.

To add Tailwind CSS to an existing Rails application, follow these two steps:

1. Add the gem to your bundle:

   ./bin/bundle add tailwindcss-rails

2. Run the installation generator:

   ./bin/rails tailwindcss:install

If you are creating a new Rails 7 application, you can preconfigure it automatically by using the --css tailwind flag:

rails new my_app --css tailwind

This gem relies on the tailwindcss-ruby gem to provide the TailwindCSS CLI executable.

To use Tailwind plugins, install them via npm or yarn so they are available in your node_modules. Then, use the @plugin annotation in your input CSS file (app/assets/tailwind/application.css).

Using npm:

npm init
npm add daisyui

Using yarn:

yarn init
yarn add daisyui

In app/assets/tailwind/application.css:

@import "tailwindcss";
@plugin "daisyui";

By default, tailwindcss-rails uses a floating dependency on tailwindcss-ruby, meaning you will receive the most recent stable version. To lock your application to a specific version of the Tailwind CSS CLI, pin the tailwindcss-ruby gem in your Gemfile.

Example of pinning to version 3.4.13:

gem "tailwindcss-rails"

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