TailwindCSS integration

INFO

This integration is especially useful when you style UI extension points with custom CSS or Tailwind classes, like custom pages and custom fields, where classes may not exist in the precompiled Avo bundle.

This integration is built for Tailwind CSS 4.

Avo ships with precompiled styles that are easy to use and work out of the box, so most apps do not need to care about extra build steps.

When Avo detects tailwindcss-ruby, it automatically enables this integration and builds an app-level Avo stylesheet with zero (or close to zero) configuration.

If you have tailwindcss-ruby installed (or tailwindcss-rails, which depends on tailwindcss-ruby) but you do not use custom Tailwind/CSS classes in custom tools, ejected components, custom fields, or other extended UI areas, you can opt out and keep using only Avo's precompiled styles.

When enabled, this integration compiles a stylesheet that includes:

• Avo core styles
• loaded Avo plugin styles
• your host app Avo styles from app/assets/stylesheets/avo/**/*.css
• utility classes discovered in your app and Avo/plugin sources

The output file is:

app/assets/builds/avo/application.css

This integration writes to the same logical Avo stylesheet path (avo/application) so your app always loads one stylesheet entrypoint.

Auto-enable behavior

Add tailwindcss-ruby to your app:

gem "tailwindcss-ruby"

Once present, Avo will:

• auto-build in development
• hook into assets:precompile in production

TIP

We highly recommend running this integration through bin/dev with a Procfile.dev watcher process:

web: bin/rails server -p 3000
avo_css: bin/rails avo:tailwindcss:watch

This keeps your Avo Tailwind build running in parallel with the Rails server, so style changes are compiled automatically while you work without extra manual steps.

Add your custom Avo styles

Add your Avo-specific stylesheets under app/assets/stylesheets/avo/.

Every CSS file in this path is included in the final avo/application.css build.

For example:

/* app/assets/stylesheets/avo/buttons.css */
@layer components {
  .avo-btn-highlight {
    @apply px-3 py-2 rounded-md bg-indigo-600 text-white;
  }
}

Disable integration (opt-out)

If your app has tailwindcss-ruby (directly or via tailwindcss-rails) but you do not need Avo custom utility coverage, disable the integration in your initializer:

Avo.configure do |config|
  config.tailwindcss_integration_enabled = false
end

Default is true.

The default is intentionally true to preserve the zero-configuration experience: if your app has tailwindcss-ruby and you start adding classes/styles in custom Avo UI extension points, this integration should just work without you needing to think about setup details.

Debugging

If classes are missing from avo/application.css, check these files first:

• input file generated by Avo: tmp/avo/avo.tailwind.input.css
• output file generated by Tailwind: app/assets/builds/avo/application.css

How it works, in short:

• Avo generates tmp/avo/avo.tailwind.input.css on each build/watch cycle.
• That input file imports Avo/plugin application.css files and your host styles from app/assets/stylesheets/avo/**/*.css.
• It also adds @source entries for Avo, loaded plugins, and your app so Tailwind can discover utility classes from templates and code.
• Tailwind then compiles everything into app/assets/builds/avo/application.css.

Quick checks:

• confirm the integration is enabled (config.tailwindcss_integration_enabled = true);
• ensure tailwindcss-ruby is installed (directly or via tailwindcss-rails);
• verify your custom styles are under app/assets/stylesheets/avo/;
• run with the watcher (bin/dev) so changes are rebuilt continuously.