Merge pull request #19 from jacob-carlborg-apoex/migrate-from-sass-rails

Add instructions how to migrate from sass-rails

Author: dhh

README.md

@@ -16,7 +16,6 @@ When you're developing your application, you want to run Dart Sass in watch mode
 1. Run `./bin/bundle add dartsass-rails`
 2. Run `./bin/rails dartsass:install`
 
-
 ## Building in production
 
 The `dartsass:build` is automatically attached to `assets:precompile`, so before the asset pipeline digests the files, the Dart Sass output will be generated.
@@ -39,6 +38,79 @@ The hash key is the relative path to a Sass file in `app/assets/stylesheets/` an
 ## Importing assets from gems
 `dartsass:build` includes application [assets paths](https://guides.rubyonrails.org/asset_pipeline.html#search-paths) as Sass [load paths](https://sass-lang.com/documentation/at-rules/use#load-paths). Assuming the gem has made assets visible to the Rails application, no additional configuration is required to use them.
 
+## Migrating from sass-rails
+
+If you're migrating from [sass-rails](https://github.com/rails/sass-rails)
+(applies to [sassc-rails](https://github.com/sass/sassc-rails) as well)
+and want to switch to dartsass-rails, follow these instructions below:
+
+1. Remove the sass-rails gem from the Gemfile by running
+
+    ```
+    ./bin/bundle remove sass-rails
+    ```
+
+1. Install dartsass-rails by following the
+    [Installation](#installation) instructions above
+
+1. Remove any references to Sass files from the Sprockets manifest file:
+    `app/assets/config/manifest.js`
+
+1. In your continues integration pipeline, before running any tests that
+    interacts with the browser, make sure to build the Sass files by running:
+
+    ```
+    bundle exec rails dartsass:build
+    ```
+
+## Troubleshooting
+
+Some common problems experienced by users ...
+
+### LoadError: cannot load such file -- sassc
+
+The reason for the above error is that Sprockets is trying to build Sass files
+but the sass-rails or sassc-rails gems are not installed. This is expected,
+since Dart Sass is used instead to build Sass files, and the solution is
+to make sure that Sprockets is not building any Sass files.
+
+There are three reasons for why this error can occur:
+
+#### Sass files are referenced in the Sprockets manifest file
+
+If any Sass files are referenced in the Sprockets manifest file
+(`app/assets/config/manifest.js`) Sprockets will try to build the Sass files and
+fail.
+
+##### Solution
+
+Remove any references to Sass files from the Sprockets manifest file. These are
+now handled by Dart Sass. If you have more Sass files than `application.scss`,
+make sure these are compiled by Dart Sass
+(see [Configuring builds](#configuring-builds) above).
+
+#### Running locally
+
+If you receive this error when running the Rails server locally and have
+already removed any references to Sass files from the Sprockets manifest file,
+the Dart Sass process is most likely not running.
+
+##### Solution
+
+Make sure the Dart Sass process is running by starting the Rails sever by
+running: `./bin/dev`.
+
+#### Running continues integration pipelines
+
+If you receive this error when running tests that interacts with the browser in
+a continues integration pipeline and have removed any references to Sass files
+from the Sprockets manifest file, the Sass files have most likely not been
+built.
+
+#####  Solution
+
+Add a step to the continues integration pipeline to build the Sass files with
+the following command: `bundle exec rails dartsass:build`.
 
 ## Version