I have found that getting Locomotive to work with Bourbon (or Susy or any addon SASS gem) is a two-stage problem. First, the resources must be loaded correctly in the Wagon gemfile, and then they must be @imported in every dependent file to compile correctly when pushed to the Engine.
To get Bourbon to import correctly into Wagon (1.5.1), add Bourbon to the gemfile in the :misc group per the sample pattern:
group :misc do
# Add your extra gems here
gem 'bourbon', require: 'bourbon'
end
Then, just run $ bundle install and it should work fine. I found that I didn't need to do $ bourbon install and have the actual .css files in my public/stylesheets folder. The gem was enough for my Wagon instance.
Pushing the site to Engine, however, can prove tricky. Wagon will compile the SASS files in an arbitrary order on push (reference: LocomotiveCMS Google Group). Consequently, the best DRY rails practice of having all your @import calls in one main sass file, and referencing only that file in a top-level application.css file won't work here:
./public/stylesheets
-application.css #requires self and main
-main.scss #imports all other stylesheets, normally where we'd @import 'bourbon'
/other_stylesheets
-variables.scss
etc. etc.
On push, Wagon won't understand that main.scss @imported Bourbon ahead of all other resources. So, it will usually fail with 'undefined mixin...'
To solve that, I still put variables.scss, mixins.scss, etc. in a folder (./public/stylesheets/base/ for instance) and call @import for those resources on every page specific stylesheet (posts.scss, etc.). In addition, any stylesheet that uses a Bourbon, Neat, Susy, whatever mixin has to call @import on that gem reference and the mixins and the variables... it has to be repeated in each dependent sheet.
./public/stylesheets
-application.css # requires self and main
-main.scss # imports all other stylesheets, normally where we'd @import 'bourbon';
/other_stylesheets
-variables.scss # might @import 'font-awesome';
-mixins.scss # @import 'bourbon'; @import 'variables';
etc. etc.
Unfortunately, this is NOT very DRY coding. In fact, there's probably a lot of bloat and redundancy that can be eliminated. So far, it's the most reliable method I've found for pushing my Wagon site to the Engine using these gems. That being said, if you're looking for a quick fix, rather than identifying each resource to @import for each page, you could make an import.scss stylesheet that calls Bourbon, Neat, what-have-you and just @import that import.scss resource into every other sheet.
The final catch (famous last words!), is that the Engine won't accept .scss or .sass files, despite the documentation. Pre-processor stylesheets have to be prepended with .css:
main.scss => main.css.scss
Otherwise, the Engine kick back an error "you are not allowed to upload..."
Hope that helps!
UPDATE:
I realized a couple weeks after posting this that the reason for the Sass troubles in Locomotive vs. other Rails apps: I was using old sprockets syntax in my application.css file.
So, the best method is to make as many Sass sheets partials as possible (prepend your filenames with an underscore -> _example.css.scss). Then, change the application.css to a Sass sheet -> application.css.scss. Finally, don't use any *= require calls like we used to with Sprockets. Instead, we can and should use the Rails best practice of Sass @import calls. You can even glob your partials in subfolders, if so inclined. The reason is, Locomotive installs sass-sprockets and sass-rails gems by default. These gems enable @import in the application.css.scss file with sprockets/asset pipeline. By using Sass partials for subsequent stylesheets, the compilation for application.css.scss will have its own domain and call the partials into it, instead of compiling each subsequent sheet in its own domain. Otherwise, you would probably see wagon push failing with 'unknown mixin...' on the first sheet outside of the main application sheet. If you order your partials in the correct order of dependency (which file does every sheet need? That goes first...), this method also has the added benefit of keeping your compiled application stylesheet very DRY.
Cheers!
