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 thevendor
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:vendor/javascript
directory and add them to your config/importmap.rb
file, eg.
application.js
:
Application entry point
Mentioned above, the application entry point is theapplication.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 theapp/javascript/controllers
directory. It will be automatically picked up by the application.
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.