Rails engine support

[flavorjones]

I wanted to start a discussion thread about support for Rails Engines and multiple Tailwind CSS files. This is an attempt to bring a few related conversations together and start to drive towards a clear understanding of the problem(s) people need solved and talk about potential solutions.

Context

There have been a few issues and pull requests around a similar set of problems. In chronological order:

• What's the 2.0 strategy for including styles seen in engines? #108
• Generator arguments do not work for engines #150
• https://stackoverflow.com/questions/71232601/how-to-use-tailwind-css-gem-in-a-rails-7-engine/
• Deploying multiple stylesheets #151
• Support multiple Tailwind css files in a project. #242

The topics from #108, #151, and #242 are related: how to support multiple CSS files, whether those are in engines/gems or elsewhere in the Rails application.

Issue #150 is slightly different and relates to full support for Rails engine generators. If we want to implement build-time support for Engines using tailwindcss, then we logically should implement generator support for Engines, too.

(The Stack Overflow thread touches on both topics.)

The problem space

Here's my first draft of articulating a problem statement (feedback welcome):

tailwindcss-rails should make it easy to write an Engine that uses Tailwind CSS.

The current tailwindcss-rails generator and its configuration both assume it's running in a top-level Rails application, and hardcodes some of those assumptions into, e.g., config/tailwind.config.js. The gem doesn't provide any ways to dynamically configure or extend this behavior.

As a result, people have fallen back on hacks like generating tailwind.config.js dynamically or forking out to bundler within tailwind.config.js to inject additional paths.

This problem statement doesn't explicitly include the "multiple Tailwind CSS files in an app" scenario from #242. In that discussion, @dhh gently pushed back on having multiple files in an app, which I think is healthy. But I suspect, if tailwindcss-rails provides a mechanism for building against assets in engines or gems, whatever mechanism we implement can be used by people to declare their separate Tailwind CSS files if they really want to do it.

The solution space

I think the broad strokes of how an engine integrates into railties are pretty well-known at this point, but broadly:

• the engine declares a dependency on the tailwindcss-rails gem
• the engine has its own tailwind config file
• which it registers in a Rails initializer, perhaps appending to config.tailwindcss_rails.config_files

Then, the gem's rake tasks tailwindcss:build and tailwindcss:watch, as well as the Puma plugin and/or the engine server hook from #347, would be extended to build multiple Tailwind CSS files.

We would also implement support for the plugin generator so that if an engine is created via rails plugin new --css tailwind then the above configuration is already in place.

Next steps

Heading into Rails Conf in about 10 days, I'm going to be at the Hack Day and would like to work on this there.

I'd love feedback from y'all on either the problem statement (did I miss a use case? does the problem statement presume too much about the shape of the solution? are there alternatives you'd like to offer) or the solution space. Thank you!

[ianterrell]

The topics from #108, #151, and #242 are related: how to support multiple CSS files, whether those are in engines/gems or elsewhere in the Rails application.
...
I'd love feedback from y'all on either the problem statement

I only want to chime in that in #108 I am not necessarily talking about building multiple CSS files per se, but rather allowing a single Tailwind generator to see all of an engine's views, partials, view components, and other files that contain Tailwind classes. When Tailwind generates its CSS file it scans all the files in the content configuration to know which utility classes it needs to include.

I know everyone working on this knows the above — I'm just including it for thoroughness since I didn't read this issue as exactly speaking to that.

the gem's rake tasks tailwindcss:build and tailwindcss:watch, as well as the Puma plugin and/or the engine server hook from #347, would be extended to build multiple Tailwind CSS files.

I may be misinterpreting this, but — I think what you're saying is that each engine would know about its own files with its own config file, and Tailwind would build a CSS file per engine which would be accessible. I don't know that it would necessarily matter, but I find it preferable to have a single Tailwind-generated CSS file. I think we're the odd ducks, but my work's main app is built with something like a Component-Based Rails Application approach, and we have ~30 engines. There would end up being a lot of duplication in each Tailwind file for our use case, and it would be cumbersome in the layouts to figure out which Tailwind CSS files to include in the header when we render view components from other components (via dependency injection).

Hopefully I haven't misinterpreted anything too much — thank you & all for the work on this gem & topic!

[flavorjones]

@ianterrell Thanks for clarifying your needs! Hearing that you've got 30+ engines and would want to render views from other engines is good information.

Maybe it would be better for engines to register their asset and view paths in an initializer, and then have just one tailwind css file? 🤔 I'm curious if this is how other folks feel, too!

[javierjulio]

@flavorjones hello and thank you. 👋🏻 As maintainer of ActiveAdmin, I'm interested in seeing this capability since with ActiveAdmin v4 beta it's now built with Tailwind but I wasn't able to use this gem successfully with an engine. Some of our users have managed to hack in tailwindcss-rails support. It would help to have the option to support multiple Tailwind config files so that way users with a large admin (or any large Rails engine) can have a separate Tailwind setup (e.g. different plugins) from their Rails app if desired.

[flavorjones]

@javierjulio Thank you for articulating your needs! The use case of a large admin is exactly what I had in mind when I made my original suggestion (multiple configs and multiple output CSS files. I really want to support this use case.

[dhh]

Would be happy to see engines supported, but imo the focus should be on expanding the files TW uses to look for classes in. Rather than trying to have multi outputs. I think in almost all cases, we're better off just producing one output for all classes found. And it'll be much easier, and we should be able to do so virtually without specific configuration.

[bopm]

there's no configuration file and it tries to intelligently scan

I find this highly unlikely and recommend checking with @adamwathan for details. Because things like raw content are being used in custom use-cases like PDF generation and cannot be replaced by just scanning the whole project.

[flavorjones]

I appreciate your incredulity, but from https://tailwindcss.com/blog/tailwindcss-v4-alpha:

You’ll notice that at least in these early alpha releases, it’s not even possible to configure your content paths. For most projects, you’re never going to need to do this ever again — Tailwind just finds your template files for you.

It also says

We’ll introduce a way to configure content paths explicitly in the future for sure, but we’re curious to see how well this automatic approach works

So maybe if I wait long enough the solution will appear. 😉

[bopm]

Don't get me wrong, but it's not the same as config going away. Ability to configure content paths probably are. But then again, ain't it incredibly wasteful to rescan every gem template on every rebuild?

I really like you to take a look at the last reply to this discussion.

[flavorjones]

The point I am trying to make is: we can't pick a solution until we understand how v4 is going to allow configuration. I said "We'll need a different approach" and "will need to explore a bit" so please don't mistake what I'm saying for anything more than that.

[bopm]

It'll allow it in full if it is more complex than this.

[mattalat]

We have a case where we manage the general front-end (basic assets, configuration, layout partials, some components) in a gem containing a Rails engine. Our teams are small and make many small, separate applications, so extracting most of the front-end matter lets us develop quickly and keeps updates centralized and more manageable.

It would be nice for us to have a way to set up and import a standard tailwind config from the gem and merge it with customizations for each app. There is almost certainly a way to do this without building it into this gem, but I thought I'd mention it anyway.

The more desired feature would be to add our gem's views and components to the paths monitored by this gem.

[hmasing]

Adding my $0.02 worth - I found this thread trying to enable precisely this use case for my platform.

Use case: We have one platform, which runs 3 flavors of front end (internal, client, and customer checkout), and on top of that, there's additional white labeling for each customer checkout that we need to support.

Our application.tailwind.css is becoming a bit of a mess of classes, namespaces, etc, and I would really like to split these out.

I am not in a position to directly contribute code, but please count me as a +1 for needing this functionality!

Thanks, all!

[nickpoorman]

I have another use case, similar to some that have already been mentioned. I have multiple websites hosted inside the same rails server process where each website is an engine mounted in the top level routes.rb. Each engine makes use of some common engines, ie. billing_engine, authentication_engine, etc.. are used by website1_engine and website2_engine.

In fact, I don't have a top level app directory and instead have a core_engine; see this presentation for the general idea: https://youtu.be/StDoHXO8H6E?si=8KVB6U5yXwHY0CsB

Ideally, I would have an isolated outputted css built for each individual engine as I don't want to load styles that belong to other websites (engines). It would also be nice to be able to reference other engine's, but that's less important to me.

I should also note that I'm using propshaft and not sprockets.

[Jasonlgrd]

Hey 👋 I have read all posts to know how I can have two tailwind configurations and I have finish here 😁

I want to contribute with the description of my use case. I have two applications :

• Back-office : to manage entites and it built with tailwindcss and Flowbite so I need special configuration for this. I use Flowbite to build faster the BO.
• Font-end : Website seeing by classic users with design system made by designer.

I need to dissociate both configurations because the design system is completely different. For the moment I choose to use tailwind without the gem and use https://tailwindcss.com/blog/tailwindcss-v3-2#multiple-config-files-in-one-project-using-config

I can't contribute of the feature development because I'm a noobie in Rails yet but I will very happy if we can use many configurations of Tailwind 🫶

Thanks of lot !

[javierav]

My two cents here. In our case we have the main application with its public and private part (it is not relevant here to optimize the styles by separating them into two different files) and then we generate PDFs using HTML and this is where it may be interesting to be able to separate the styles to avoid sending the converter the styles that are not necessary, but I think a bit like dhh, it is more for optimization than a technical necessity.

Thanks for the effort!

[bopm]

While waiting for a response to the thread here, I decided to explore different approaches and implement an installation script that collects tailwind classes from tailwind.css of my engine and adds them to raw configuration of my host app.
https://github.com/full-stack-biz/turbo_material/blob/develop/lib/generators/turbo_material/install_generator.rb#L18-L45

[DavidGeismarLtd]

Hey there ! Same need here :
Multitenant app with different themes (color, spacing...) handled by the same rails app.
So we need to be able to generate different output file based on different tailwind config file.
I guess we thus need the watch process to be able to handle different files based on those different configs.
Has anyone built a workaround to this yet ?

[flavorjones]

Hi! Can you say more about your particular use case? It sounds like perhaps each tenant can dynamically configure the style on their (white-labeled) site, but I'd love to confirm that with you.

I'm curious, is there a reason you couldn't use tailwindcss-ruby (maybe run in a background job) to generate a CSS file for each tenant as their styles are updated?

[code-bunny]

Did we get any traction on engine support. I am off trying it today and expected it to just work out the box until it didn't. What the current best way to work with engines?

[flavorjones]

It's not supported at this time. The conversation above includes proposals for a few different approaches we might take for different use cases.

Specifically, in this discussion we're trying to define what problem (or problems) we specifically want to solve. Could you share what you expected "engine support" to mean? I.e., do you expect a distinct CSS file for each engine, or do you expect all engines to be scanned and represented in a single global CSS file (or something else)?

[flavorjones]

What the current best way to work with engines?

One way to do this is to add your engine paths into your tailwind.config.js file, which should then include the engines' styles in the global application.tailwind.css.

[code-bunny]

I can imagine two options:

• Each engine has a tailwind.config that is automatically inherited by the main applications tailwindcss. Given that Tailwindcss should have no conflicting styles, this would allow a 'magic' stylesheet_link_tag "main_app.tailwind", "inter-font", "data-turbo-track": "reload" stylesheet for the engine.
• For engines where the author does not intend nor rely on the host to have tailwind we have a engine_name.tailwind generated that is fully self contained. However since we still need to run tailwindcss in the Procfile.dev the writer of said engine would be responsible for including this as part of the engine install.

The second option fits my use case the best where I want all my front end in an isolated engine as the main app is a container for three API engines and then the admin engine(which needs tailwindcss). Having the main app cluttered with a stylesheet folder and tailwindcss config isn't great. This also works for when you are mounting several frontend engines in one container app and want tailwind to build isolated stylesheets for each engine so there is no bleeding.