DOCSEARCHbyAlgolia
Submit Docs

cssbundling-rails

repository·main·Indexed 20 days ago

https://github.com/rails/cssbundling-rails

A Rails engine that enables the use of modern CSS bundlers such as Tailwind CSS, Bootstrap, Bulma, PostCSS, and Dart Sass within the Rails asset pipeline. It manages the build process via Node/Yarn and integrates with Rails' deployment and testing lifecycles, providing a full Node-based bundling environment for applications already relying on Node to process JavaScript.

Tokens
1.2K
Snippets
5
Records
9
Agent score
21%

What's inside cssbundling-rails

  1. How CSS Bundling for Rails works

    main

    This gem uses a Node-based bundler to process stylesheets and delivers the output via the Rails asset pipeline.

    Development Workflow

    • Watch Mode: Run yarn build:css --watch in a terminal to automatically recompile CSS when files change.
    • Unified Dev Command: Use ./bin/dev to start both the Rails server and the CSS build watcher (and JS watcher if using jsbundling-rails).
    • Output Convention: The bundler takes an entrypoint at app/assets/stylesheets/application.[bundler].css and outputs the result to app/assets/builds/application.css. This directory is added to .gitignore by default.
    • Asset Linking: In your layouts, continue using the standard asset pipeline helper:
      <%= stylesheet_link_tag "application" %>

    Production and Testing

    • Production: The css:build task is attached to assets:precompile. It ensures yarn dependencies are installed and runs yarn build:css before the asset pipeline digests and copies the files to public/assets.
    • Testing: The css:build task is attached to test:prepare. If your test framework does not call test:prepare, you must manually run css:build (and javascript:build if using jsbundling-rails) before running tests.

  2. Compare cssbundling-rails with tailwindcss-rails and dartsass-rails

    main

    Choose your integration based on your existing JavaScript workflow:

    • Use cssbundling-rails: If you are already relying on Node to process your JavaScript. This provides a full Node-based bundling environment.
    • Use tailwindcss-rails or dartsass-rails: If you are using the default Import Map setup in Rails 7+. These are standalone versions that allow you to avoid managing Node/Yarn entirely. They are simpler and have fewer moving parts.

    In Rails 7+, you can preconfigure these standalone versions with:

    rails new myapp --css [tailwind|sass]

  3. Import 3rd party stylesheets from node_modules

    main

    To include a stylesheet from a package installed via yarn, use an @import statement. Omit the node_modules/ segment and the file extension.

    Example: To import node_modules/select2/dist/css/select2.css:

    @import "select2/dist/css/select2";
    @import "select2/dist/css/select2";

  4. Import relative CSS files with Tailwind CSS 4

    main

    Tailwind CSS 4 uses native CSS configuration. Instead of bundling everything into one file, you can reference individual CSS files directly in your layout to improve caching and simplify setup.

    Update your application.html.erb to include multiple files in the stylesheet_link_tag:

    <%= stylesheet_link_tag "application", "other", "styles", "data-turbo-track": "reload" %>
    <%= stylesheet_link_tag "application", "other", "styles", "data-turbo-track": "reload" %>

  5. Install CSS Bundling for Rails

    main

    To use Tailwind CSS, Bootstrap, Bulma, PostCSS, or Dart Sass with a Node-based workflow in Rails, follow these steps. You must have node, yarn, and npx (version 7.1.0 or later) installed on your system.

    For an existing application

    1. Add the gem:
      ./bin/bundle add cssbundling-rails
    2. Run the installer for your chosen bundler:
      ./bin/rails css:install:[tailwind|bootstrap|bulma|postcss|sass]

    For a new application (Rails 7+)

    You can preconfigure your application during creation using the --css flag:

    rails new myapp --css [bootstrap|bulma|postcss]
    #!/bin/bash
./bin/bundle add cssbundling-rails
./bin/rails css:install:tailwind

  6. Troubleshoot SassC::SyntaxError on existing projects

    main

    If you encounter SassC::SyntaxError during assets:precompile, it is likely because your CSS uses features not supported by the legacy sass-rails or sassc-rails gems.

    Fix: Remove the legacy gem:

    bundle remove sass-rails
# or
bundle remove sassc-rails

  7. Fix 'Function rgb is missing argument $green' error

    main

    This error can occur if sassc-rails is present in your Gemfile.lock (either directly or as a transitive dependency), causing Sprockets to attempt to bundle CSS that has already been processed by this gem.

    Fix: Disable the Sprockets CSS compressor in config/initializers/assets.rb for all environments:

    # config/initializers/assets.rb
Rails.application.config.assets.css_compressor = nil
    # config/initializers/assets.rb
Rails.application.config.assets.css_compressor = nil

  8. Fix Rails not using updated CSS files

    main

    If you have previously run assets:precompile locally, Rails may serve those precompiled files instead of the new ones generated by your bundler.

    Fix: Clear your assets with:

    rails assets:clobber
    rails assets:clobber

  9. Fix 'application.css not in asset pipeline' in production

    main

    This error occurs if the app/assets/builds directory is missing from your repository when deploying.

    Fix: Ensure the directory exists by adding a .keep file to it:

    touch app/assets/builds/.keep