Custom JavaScript for Spree Storefront
Learn how to add custom JavaScript to your Spree storefront
Extending Storefront with JavaScript
Spree Storefront can be easily extended with custom JavaScript. Most of the JavaScript in the storefront is powered by a framework called Stimulus.js which is the Ruby on Rails default. It’s a very simple and minimalistic framework only enhancing our server-side rendered HTML with a bit of interactivity.
3rd party JavaScript libraries
Spree Storefront comes with a few 3rd party JavaScript libraries already included.
Main libraries we’re using:
You can find them in the app/assets/javascripts/vendor directory.
Managing JavaScript dependencies
You’re probably wondering why these libraries are in the vendor
directory, and not in node_modules
.
That’s because we’re not using Node.js at all. So no Yarn or npm. We’re using a different approach to manage dependencies.
We’re using a tool called Importmaps to manage dependencies which is the Ruby on Rails default.
If you want to use a different JavaScript package manager you can do so by using jsbundling-rails gem.
Install dependencies
To install dependencies you need to run the following command:
This will install the dependencies, download the files to your vendor/javascript
directory and add them to your config/importmap.rb
file, eg.
Now you can just import the library in your application entry point, eg. application.js
:
Application entry point
Mentioned above, the application entry point is the application.js
file. It’s located in the app/javascript
directory.
If you want to add custom JavaScript to your Spree storefront, you can do so by adding a new file to the app/javascript
directory.
Stimulus Controllers
Stimulus controllers are a way to add interactivity to your Spree storefront. Storefront controllers can be found in the Spree repository in the storefront/app/javascript/spree/storefront/controllers directory.
You can find more information about Stimulus controllers in the Stimulus.js documentation.
To add a new controller you need to create a new file in the app/javascript/controllers
directory. It will be automatically picked up by the application.
To use the controller in your HTML you need to add the data-controller
attribute to your element, eg.
JavaScript snippets
If you need to add a small piece of JavaScript code (eg. tracking, marketing, analytics, customer service etc.) you can do this by:
-
Declaring a new head partial in the
config/initializers/spree.rb
file, eg. -
Creating a new file in the
app/views/spree/shared/my_tracking_code.html.erb
, where you can add your tracking code, eg.
With Spree 5.1 we’re going to release a new integrations feature which will allow you to easily connect your storefront to third party services, eg. Google Analytics, Facebook Pixel, etc.