Implement Engines Support (#554)

bopm · flavorjones · web-flow · commit a66db017913c · 2025-06-12T10:22:30.000-04:00
* Implement Engines Support

* Correction in README.md

* Remove engine test

* Rename to engine.css

* Initial test cleanup

* Tests cleanup

* Remove non-needed dup

* Correction

* Correct docs

* doc: update README to indicate engine support is experimental

---------

Co-authored-by: Mike Dalessio &lt;mike@37signals.com&gt;
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    tailwindcss-rails (4.2.2)
+    tailwindcss-rails (4.2.3)
       railties (>= 7.0.0)
       tailwindcss-ruby (~> 4.0)
 
diff --git a/README.md b/README.md
@@ -23,7 +23,9 @@
   * [Using Tailwind plugins](#using-tailwind-plugins)
   * [Using with PostCSS](#using-with-postcss)
   * [Custom inputs or outputs](#custom-inputs-or-outputs)
+  * [Rails Engines support (Experimental)](#rails-engines-support-experimental)
 - [Troubleshooting](#troubleshooting)
+  * [The `watch` command is hanging](#the-watch-command-is-hanging)
   * [Lost keystrokes or hanging when using terminal-based debugging tools (e.g. IRB, Pry, `ruby/debug`...etc.) with the Puma plugin](#lost-keystrokes-or-hanging-when-using-terminal-based-debugging-tools-eg-irb-pry-rubydebugetc-with-the-puma-plugin)
   * [Running in a docker container exits prematurely](#running-in-a-docker-container-exits-prematurely)
   * [Conflict with sassc-rails](#conflict-with-sassc-rails)
@@ -43,12 +45,11 @@ With Rails 7 you can generate a new application preconfigured with Tailwind CSS
 
 This gem depends on the `tailwindcss-ruby` gem to install a working Tailwind 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,
 
-``` ruby
+```ruby
 gem "tailwindcss-rails"
 
 # pin to tailwindcss version 3.4.13
@@ -59,7 +60,6 @@ gem "tailwindcss-ruby", "3.4.13"
 
 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.
@@ -72,36 +72,34 @@ This gem will help with some of the mechanics of the upgrade:
 - update some local project files to meet some Tailwind CSS v4 conventions,
 - attempt to run the [upstream v4 upgrade tool](https://tailwindcss.com/docs/upgrade-guide#using-the-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:
 
-``` ruby
+```ruby
 # 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`:
 
-``` ruby
+```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](#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.
 
-```html
-# Gemfile
+```ruby
+# Gemfile 
 gem "tailwindcss-rails", "~> 4.0" # which transitively pins tailwindcss-ruby to v4
 ```
 
@@ -114,7 +112,7 @@ gem "tailwindcss-rails", "~> 4.0" # which transitively pins tailwindcss-ruby to
 
 If you want to migrate CSS class names for v4 (this is an optional step!), jump to [Updating CSS class names for v4](#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.
+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.
 
 <details>
 <summary>Here's a detailed list of what the upgrade task does.</summary>
@@ -131,7 +129,7 @@ Then, run `bin/rails tailwindcss:upgrade`. Among other things, this will try to
 <details>
 <summary>Here's what that upgrade looks like on a vanilla Rails app.</summary>
 
-``` sh
+```sh
 $ 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
@@ -166,12 +164,11 @@ $ bin/rails tailwindcss:upgrade
 Done in 56ms
          run  bundle install --quiet
 ```
-</details>
 
+</details>
 
 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](https://tailwindcss.com/docs/upgrade-guide) and try following the additional steps in [Updating CSS class names for v4](#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](https://github.com/rails/tailwindcss-rails/discussions/450) if you're having trouble upgrading.
@@ -182,7 +179,6 @@ We know there are some cases we haven't addressed with the upgrade task:
 
 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]
@@ -208,9 +204,9 @@ With some additional manual work the upstream upgrade tool will update your appl
     "@tailwindcss/aspect-ratio": "^0.4.2",
     "@tailwindcss/container-queries": "^0.1.1",
     "@tailwindcss/forms": "^0.5.10",
-    "@tailwindcss/typography": "^0.5.16"
+    "@tailwindcss/typography": "^0.5.16",
     // And so on...
-  }
+  },
 }
 ```
 
@@ -280,12 +276,10 @@ This gem also generates a `Procfile.dev` file which will run both the rails serv
 
 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:
@@ -303,7 +297,6 @@ While you're developing your application, you want to run Tailwind in "watch" mo
 - or run `rails tailwindcss:watch` as a separate process,
 - or run `bin/dev` which uses [Foreman](https://github.com/ddollar/foreman)
 
-
 #### Puma plugin
 
 This gem ships with a Puma plugin. To use it, add this line to your `puma.rb` configuration:
@@ -314,7 +307,6 @@ 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.
@@ -331,38 +323,35 @@ If you are running `rails tailwindcss:watch` as a process in a Docker container,
 
 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 Tailwind plugins
 
 If you want to use Tailwind plugins, they can be installed using `package.json`.
 
 Using Yarn:
 
-``` sh
+```sh
 [ ! -f package.json ] && yarn init
 yarn add daisyui # example
 ```
 
 Using npm:
 
-``` sh
+```sh
 npm init
 npm add daisyui # example
 ```
 
 Than use `@plugin` annotation in `app/assets/tailwind/application.css`:
 
-``` css
+```css
 @import "tailwindcss";
 @plugin "daisyui";
 ```
 
-
 ### 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.
@@ -374,8 +363,8 @@ For example, to enable nesting:
 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:
@@ -395,11 +384,18 @@ export default {
 
 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.
 
+### Rails Engines support (Experimental)
+
+_This feature is experimental and may change in the future. If you have feedback, please join the [discussion](https://github.com/rails/tailwindcss-rails/discussions/355)._
+
+If you have Rails Engines in your application that use Tailwind CSS and provide an `app/assets/tailwind/<engine_name>/engine.css` file, entry point files will be created for each of them in `app/assets/builds/tailwind/<engine_name>.css` so they can be included in your host application's Tailwind CSS by adding `@import "../builds/tailwind/<engine_name>"` to your `app/assets/tailwind/application.css` file.
+
+> [!IMPORTANT]
+> You must `@import` the engine CSS files in your `app/assets/tailwind/application.css` for the engine to be included in the build. By default, no engine CSS files are imported, and you must opt-in to using the file in your build.
 
 ## Troubleshooting
 
@@ -410,7 +406,7 @@ When having trouble with `tailwindcss:build` or `tailwindcss:watch`, the first t
 
 Here's what that looks like:
 
-``` sh
+```sh
 $ bin/rails tailwindcss:build[verbose]
 
 Running: /path/to/tailwindcss-ruby-4.0.17-x86_64-linux-gnu/exe/x86_64-linux-gnu/tailwindcss -i /home/flavorjones/code/oss/tailwindcss-rails/My Workspace/test-install/app/assets/tailwind/application.css -o /home/flavorjones/code/oss/tailwindcss-rails/My Workspace/test-install/app/assets/builds/tailwind.css --minify
@@ -432,34 +428,28 @@ There is a [known issue](https://github.com/tailwindlabs/tailwindcss/issues/1724
 
 Please try uninstalling `watchman` and try running the watch task again.
 
-
 ### 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](https://github.com/rails/tailwindcss-rails/releases/tag/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](https://tailwindcss.com/docs/content-configuration#safelisting-classes).
 
-
 ### `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](https://guides.rubyonrails.org/asset_pipeline.html#fingerprinting-versioning-with-digest-based-urls). However, Tailwind isn't aware of those assets.
@@ -468,20 +458,22 @@ To use assets from the pipeline, use `url(image.svg)`. [Since Sprockets v3.3.0](
 
 ```js
 module.exports = {
-    theme: {
-        extend: {
-            backgroundImage: {
-                'image': "url('image.svg')"
-            }
-        }
-    }
-}
+  theme: {
+    extend: {
+      backgroundImage: {
+        image: "url('image.svg')",
+      },
+    },
+  },
+};
 ```
 
 The inline version also works:
 
 ```html
-<section class="bg-[url('image.svg')]">Has the image as it's background</section>
+<section class="bg-[url('image.svg')]">
+  Has the image as it's background
+</section>
 ```
 
 ## License
diff --git a/lib/tailwindcss-rails.rb b/lib/tailwindcss-rails.rb
@@ -2,5 +2,6 @@ module Tailwindcss
 end
 
 require_relative "tailwindcss/version"
+require_relative "tailwindcss/engines"
 require_relative "tailwindcss/engine"
 require_relative "tailwindcss/commands"
diff --git a/lib/tailwindcss/engine.rb b/lib/tailwindcss/engine.rb
@@ -15,5 +15,9 @@ class Engine < ::Rails::Engine
     config.app_generators do |g|
       g.template_engine :tailwindcss
     end
+
+    config.after_initialize do
+      Tailwindcss::Engines.bundle
+    end
   end
 end
diff --git a/lib/tailwindcss/engines.rb b/lib/tailwindcss/engines.rb
@@ -0,0 +1,23 @@
+module Tailwindcss
+  module Engines
+     class << self
+      def bundle
+        FileUtils.mkdir_p(Rails.root.join("app/assets/builds/tailwind"))
+        Rails::Engine.subclasses.select do |engine|
+          engine.root.join("app/assets/tailwind/#{engine.engine_name}/engine.css").exist?
+        end.each do |engine|
+          file_path = Rails.root.join("app/assets/builds/tailwind/#{engine.engine_name}.css")
+          FileUtils.rm(file_path) if File.exist?(file_path)
+          template = <<~TEMPLATE
+            /* DO NOT MODIFY THIS FILE, it was auto-generated by tailwindcss-rails */
+
+            @import "#{engine.root.join("app/assets/tailwind/#{engine.engine_name}/engine.css")}";
+          TEMPLATE
+          File.open(file_path, 'w') do |file|
+            file.puts template
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/test/lib/tailwindcss/engines_test.rb b/test/lib/tailwindcss/engines_test.rb
