<%= content_for(:title) || "Your App" %>

TITLE: How to Add Tailwind CSS v4 to a Rails 8 Project ⚠️ This is not an upgrade guide. That is well documented in the [Upgrading your application from Tailwind v3 to v4](https://github.com/rails/tailwindcss-rails?tab=readme-ov-file#upgrading-your-application-from-tailwind-v3-to-v4) section of the Tailwind css Rails gem. The easiest way to add Tailwind css v4 to your Rails 8 project is to follow the [Ruby on Rails framework guide](https://tailwindcss.com/docs/installation/framework-guides/ruby-on-rails) instructions from the Tailwind CSS docs. If that's still not working, here's a step by step guide that shows new files that need to be created and other files that need to be modified. ## Installation Steps ### 1. Add Tailwind CSS Ruby and Rails Gems Add this line to your `Gemfile`: ```ruby # Use Tailwind CSS [https://github.com/rails/tailwindcss-rails] gem "tailwindcss-rails" # Use Tailwind CSS [https://github.com/tailwindlabs/tailwindcss-ruby] gem "tailwindcss-ruby" ``` Then run: ```bash bundle install ``` ### 2. Set Up Asset Structure Create the necessary directories and files: ```bash # Create the builds directory and keep file mkdir -p app/assets/builds touch app/assets/builds/.keep # Create the tailwind directory and config mkdir -p app/assets/tailwind echo '@import "tailwindcss";' > app/assets/tailwind/application.css ``` ### 3. Update .gitignore Add these lines to your `.gitignore` file to ignore generated builds while keeping the directory structure: ``` /app/assets/builds/* !/app/assets/builds/.keep ``` ### 4. Set Up Process Management Create a `Procfile.dev` in your project root with the following content: ```yaml web: bin/rails server css: bin/rails tailwindcss:watch ``` Update your `bin/dev` script to use Foreman for process management: ```bash #!/usr/bin/env sh if ! gem list foreman -i --silent; then echo "Installing foreman..." gem install foreman fi # Default to port 3000 if not specified export PORT="${PORT:-3000}" # Let the debug gem allow remote connections, # but avoid loading until `debugger` is called export RUBY_DEBUG_OPEN="true" export RUBY_DEBUG_LAZY="true" exec foreman start -f Procfile.dev "$@" ``` Make the dev script executable: ```bash chmod +x bin/dev ``` ### 5. Update Your Layout When adding Tailwind CSS to your existing Rails application, you need to make two critical changes to your layout file: 1. Add the Tailwind CSS stylesheet link tag 2. Optionally add Tailwind utility classes to your HTML structure #### Adding the Tailwind Stylesheet In your `app/views/layouts/application.html.erb` file, add the Tailwind stylesheet link tag **before** your application stylesheet: ```erb <%# Add this line before your existing stylesheet_link_tag %> <%= stylesheet_link_tag "tailwind", "data-turbo-track": "reload" %> <%# Keep your existing stylesheet %> <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %> ``` #### Preserving Existing Layout Features Many Rails applications have existing features in their layout files, such as PWA support, custom meta tags, or icon configurations. Here's how to preserve these while adding Tailwind: ```erb <%= content_for(:title) || "Your App" %> <%# Preserve all your existing meta tags %> <%= csrf_meta_tags %> <%= csp_meta_tag %> <%# Keep any content_for blocks %> <%= yield :head %> <%# Preserve PWA manifest support %> <%#= tag.link rel: "manifest", href: pwa_manifest_path(format: :json) %> <%# Keep your favicon and app icon configurations %> <%# Add Tailwind CSS before your existing stylesheets %> <%= stylesheet_link_tag "tailwind", "data-turbo-track": "reload" %> <%# Keep your existing stylesheets - might be "application" or a custom name %> <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %> <%# Preserve your JavaScript imports %> <%= javascript_importmap_tags %> <%# Preserve your existing layout structure %> <%# Add Tailwind utility classes as needed %>

<%= yield %>

``` #### Key Considerations: 1. **Stylesheet Order**: Always add the Tailwind stylesheet before your application stylesheet to allow your custom styles to override Tailwind defaults. 2. **Progressive Web App (PWA) Support**: Tailwind works seamlessly with PWA configurations. Keep your existing PWA meta tags and manifest links. 3. **Meta Tags**: Preserve all your custom meta tags for SEO, mobile functionality, and social sharing. 4. **Icons**: Maintain your existing favicon and app icon configurations. 5. **Content Blocks**: Keep any `content_for` blocks and other dynamic content in your layout. 6. **Layout Structure**: Only add Tailwind utility classes to elements where you want the styling applied. You can gradually adopt Tailwind by incrementally adding classes. ## Usage ### Starting the Development Server Instead of using `rails server`, now use: ```bash bin/dev ``` This will start both: - The Rails server - The Tailwind CSS watcher (which compiles your CSS in real-time) ### Verifying Installation 1. Start your server using `bin/dev` 2. Add some Tailwind CSS classes to one of your views: ```html

Hello Tailwind CSS!

``` 3. Visit the page in your browser to confirm that Tailwind CSS styles are being applied ## Common Issues and Solutions 1. **If Tailwind CSS styles aren't applying:** - Ensure your layout file is properly importing the Tailwind CSS stylesheet - Check that the Tailwind CSS watcher is running (you should see it in the `bin/dev` output) - Clear your asset cache: `bin/rails assets:clean` - Verify that you've added `stylesheet_link_tag "tailwind"` before your application stylesheet 2. **If `bin/dev` fails to start:** - Ensure Foreman is installed: `gem install foreman` - Check that your `Procfile.dev` is in the root directory - Verify that both the `web` and `css` processes are properly configured 3. **If you get an error about missing `tailwindcss` executable:** - Make sure you've run `bundle install` - Try running `bundle exec rails tailwindcss:install` to ensure the executable is installed 4. **Issues with existing layouts and PWA features:** - If your PWA features stop working, ensure you've preserved all manifest links and meta tags - If custom stylesheets are overridden by Tailwind, make sure your application stylesheet comes after Tailwind - If layout looks inconsistent, gradually add Tailwind classes rather than applying them all at once - For completely custom styling, consider using `@layer` directives in your CSS to work with Tailwind ## Additional Tips - Remember to restart your server when making changes to your Gemfile - The Tailwind CSS watcher will automatically recompile when you make changes to your CSS - You can customize your Tailwind configuration by running `rails tailwindcss:config` (optional) ## References - [Tailwind CSS Rails Gem](https://github.com/rails/tailwindcss-rails) - [Rails Asset Pipeline Guide](https://guides.rubyonrails.org/asset_pipeline.html) - [Tailwind CSS Documentation](https://tailwindcss.com/docs)