---
title: "Howto migrate from Webpacker to cssbundling-rails in Ruby on Rails for CSS"
description: "Migrating an existing Ruby on Rails Application using webpacker to cssbundling-rails for CSS bundling."
url: "https://qameta.com/posts/howto-migrate-from-webpacker-to-cssbundling-rails-in-ruby-on-rails/"
image: "https://qameta.com/images/posts/webpacker-to-css-bundling-in-ruby-on-rails.png"
---

# Howto migrate from Webpacker to cssbundling-rails in Ruby on Rails for CSS

![Using cssbundling-rails for CSS pipeline](https://qameta.com/images/posts/webpacker-to-css-bundling-in-ruby-on-rails.png)

A lot of [Ruby on Rails](https://rubyonrails.org) applications created with Ruby
on Rails version 5.x or 6.x or even upgraded from the previous versions are
using [webpacker](https://github.com/rails/webpacker) as their primary asset
pipeline. But now as webpacker has retired, it is time to move on.
[cssbundling-rails](https://github.com/rails/cssbundling-rails) is or will be
the most obvious step to go.

If you were using webpack(er) for [CSS](https://en.wikipedia.org/wiki/CSS) too
as I did, I recommend moving your CSS pipeline to an alternative before moving
your [JavaScript](https://en.wikipedia.org/wiki/JavaScript) setup to an
alternative like [jsbundling-rails](https://github.com/rails/jsbundling-rails)
or [importmap-rails](https://github.com/rails/importmap-rails).

## Why move at all?

As previously said, [webpacker](https://github.com/rails/webpacker) was sunset
and development already stopped 2021. Also, webpacker has a lot of old
dependencies, especially [webpack](https://github.com/webpack/webpack) version 3
which can't be upgraded.

Webpacker suffers a lot of problems that were never solved and now never would
be solved at all. It was pretty hard to set up, but delivered quite a lot of
useful and needed features back in the days when only sprockets were the only
option for handling assets.

## Prepare your project

First of all, you have to upgrade your project to at least rails 6.1.x (better
rails 7.0.x) as it has everything prepared to get your project on
cssbundling-rails. According to Gemfile from
[cssbundling-rails](https://github.com/rails/cssbundling-rails/blob/main/Gemfile)
Ruby on Rails 6.1.0 is the minimum version.

I've tried to get all of my projects to current rails (current is 7.0.x) as
priority one before I tackle such issues. But this is your decision. Ruby on
Rails 6.1.X is enough for this step.

### First move to cssbundling-rails before starting jsbundling-rails

As first steop move your css setup to cssbundling-rails and then start moving
your JavaScript to jsbundling-rails. If you are a looking for a tutorial to move
your project to jsbundling-rails I've written one too:

* [Howto migrate from Webpacker to jsbundling-rails in Ruby on
  Rails](https://qameta.com/posts/howto-migrate-from-webpacker-to-jsbundling-rails-in-ruby-on-rails/)

## Install cssbundling-rails gem

Install [cssbundling-rails](https://github.com/rails/cssbundling-rails/) first
by running:

```sh
./bin/bundle add cssbundling-rails
```

You can also add it manually to your Gemfile and run `bundle install` to install
it.

## Select and run the setup you are using

[cssbundling-rails](https://github.com/rails/cssbundling-rails) has a lot of
different install options you can use:

* [tailwind](https://tailwindcss.com)
* [bootstrap](https://getbootstrap.com/)
* [bulma](https://bulma.io)
* [postcss](https://postcss.org)
* [sass](https://sass-lang.com) using
  [npm sass](https://www.npmjs.com/package/sass)

To make it as simple as possible, just use the setup you had previously used
within your project. The first step is always to get your previous setup
working with the new system.

Check which one is yours:

```sh
./bin/rails css:install:[tailwind|bootstrap|bulma|postcss|sass]
```

As a lot of my projects are using bootstrap, I'll show here the bootstrap option
as an example.

### Using Bootstrap default setup with cssbundling-rails

I use the `bootstrap` option to show how the default setup is done using
[cssbundling-rails](https://github.com/rails/cssbundling-rails). You can move it
to `postcss` or `sass` later. Just use the default options to get familiar with
it and has a running project as soon as possible.

```sh
./bin/rails css:install:bootstrap
```

Follow the setup assistant. As with most existing (legacy) projects you may
encounter more or fewer changes and errors you need to fix first.

### Starting in development through bin/dev

If you were starting your project manually or from a script not named
`bin/dev`, you may align it to the new rails default.

Your *Procfile.dev* should look something like this in diff:

```diff
diff --git a/Procfile.dev b/Procfile.dev
index 813d8e3..f418999 100644
--- a/Procfile.dev
+++ b/Procfile.dev
@@ -1,2 +1,3 @@
 web: bin/rails server -p $PORT
 webpack: bin/webpack-dev-server
+css: yarn build:css --watch
```

You can start your project by running *bin/dev* which should look like this:

```sh
#!/usr/bin/env sh

if ! gem list foreman -i --silent; then
  echo "Installing foreman..."
  gem install foreman
fi

exec foreman start -f Procfile.dev "$@"
```

If you could start the project and it was working, then you are like but most
people won't.

### Downgrading bootstrap to the used version

Not all projects will be on the newest [Bootstrap](https://getbootstrap.com)
version (currently 5.2.3). You have to align *package.json* to your previous
setup:

```diff
diff --git a/package.json b/package.json
...
   "dependencies": {
     "@rails/ujs": "^7.0.0",
     "@rails/webpacker": "^5.2.1",
     "bootstrap": "^4.6.0",
+    "bootstrap-icons": "^1.10.3",
     "jquery": "^3.6.0",
     "popper.js": "^1.16.1",
+    "sass": "^1.58.0",
     "stimulus": "^3.0.0",
   },
...
```

Now run `yarn install` to have the right dependencies installed.

Installing *bootstrap-icons* is optional. If you don't use them, just remove the
dependency. You can add it if you want to use them.

## Move your CSS setup from webpacker to cssbundling-rails

Dependent on your setup, you may have more or fewer customizations on your
[Bootstrap](https://getbootstrap.com) setup.

As the first step I removed all CSS-related imports from
*app/javascript/packs/application.js*:

```sh
diff --git a/app/javascript/packs/application.js b/app/javascript/packs/application.js

// Import CSS
-import 'css/application'
+// import 'css/application'
```

As next step use the new CSS file generated by cssbundling-rails:

```diff
diff --git app/views/layouts/application.html.erb app/views/layouts/application.html.erb

-<%= stylesheet_pack_tag 'application', media: 'all',
-    'data-turbolinks-track': 'reload' %>
+<%= stylesheet_link_tag 'application', media: 'all',
+   'data-turbolinks-track': 'reload', defer: true %>
```

**HINT:** cssbundling-rails is loading
`app/assets/stylesheets/application.bootstrap.scss` but you have to link the
output file which is named `application.css`. That's why you have to link to
the `application`.

### Update scss/sass file to your preferred name

You can rename the main CSS file to something else. I prefer to use a default
`application.scss` and include the relevant files like a custom
[Bootstrap](https://getbootstrap.com) file, which imports only relevant parts of
Bootstrap.

There are only 2 steps to have it as you want:

* Rename the file `app/assets/stylesheets/application.bootstrap.scss` to
  `app/assets/stylesheets/application.scss`
* Let yarn load the new file through **package.json** by changing:


```diff
diff --git a/package.json b/package.json

   "scripts": {
-    "build:css": "sass ./app/assets/stylesheets/application.bootstrap.scss:./app/assets/builds/application.css --no-source-map --load-path=node_modules"
+    "build:css": "sass ./app/assets/stylesheets/application.scss:./app/assets/builds/application.css --no-source-map --load-path=node_modules"
   }
```

You can even use a sass file instead of scss if you want. The change should be
obvious by renaming your `application.scss` file to `application.sass`.

### Move your scss and css files to the new location

As all my css files were located in `app/javascript/css/` folder. I moved them
to `app/assets/stylesheets`.

Including them is as simple as it was before. There are view things you have to
consider.

Before you just added the name of the file in the current directory and
[webpack](https://github.com/webpack/webpack) did the work to find the right
one. Now you have to tell sass, that the file is in the current directory:

```diff
dif --git app/javascript/packs/application.scss app/assets/stylesheets/application.scss

-@include 'custom';
+@include './custom';
```

If you have included something from [node_modules](https://www.npmjs.com), it
mostly will stay the same. Previously you had to tell, that it is a .css file.
Now you set the path to the file without giving `.css` or `.scss` at the end:

```diff
dif --git app/javascript/packs/application.scss app/assets/stylesheets/application.scss

-@import 'tom-select/dist/css/tom-select.bootstrap5.css';
+@import 'tom-select/dist/css/tom-select.bootstrap5';
```

If you have added only relevant CSS files from
[Bootstrap](https://getbootstrap.com) in your project, the imports look now a
little bit different (without `~`):

```diff
diff --git app/javascript/css/bootstrap_custom.scss app/assets/stylesheets/bootstrap_custom.scss

-@import '~bootstrap/scss/_breadcrumb';
+@import 'bootstrap/scss/_breadcrumb';
```

## Updating your deployment system

As you are now using [webpacker](https://github.com/rails/webpacker) and
sprockets-rails in parallel, you need to trigger both systems on deployment.

### GitHub Actions (CI)

For [GitHub Actions](https://docs.github.com/en/actions) as CI system the change
is pretty easy. You just have to add the sprockets command:

```diff
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml


-      - name: Webpack(er) compilation
-        run: NODE_ENV=test bundle exec rails webpacker:compile
+      - name: Assets and Webpack(er) compilation
+        run: |
+          bundle exec rails assets:precompile
+          NODE_ENV=test bundle exec rails webpacker:compile
```

### Capistrano

The change for [capistrano](https://github.com/capistrano/) is pretty straight
forward. Just enable assets compilation in your Capfile:

```diff
diff --git Capfile Capfile

-#require 'capistrano/rails/assets'
+require 'capistrano/rails/assets'
require 'capistrano/webpacker/precompile'
```

## Summary

Moving from [webpack(er)](https://github.com/rails/webpacker) packed CSS setup
to [cssbundling-rails](https://github.com/rails/cssbundling-rails) is pretty
straightforward, if you know of small differences in using **sass** and
**webpack** in development. I tried to tell here the most common things you may
encounter.

The next step should be to move from
[webpacker](https://github.com/rails/webpacker) to using
[jsbundling-rails](https://github.com/rails/jsbundling-rails) with esbuild or
[webpack](https://github.com/webpack/webpack) as
[JavaScript](https://en.wikipedia.org/wiki/JavaScript) build system.

If you want to move your JavaScript to jsbundling-rails here is the next
tutorial:

* [Howto migrate from Webpacker to jsbundling-rails in Ruby on
  Rails](https://qameta.com/posts/howto-migrate-from-webpacker-to-jsbundling-rails-in-ruby-on-rails/)

Happy coding!
