Custom JavaScript for Admin Dashboard

Extending Admin Dashboard with JavaScript

Spree Admin Dashboard can be easily extended with custom JavaScript. Most of the JavaScript in the Admin Dashboard is powered by a framework called Stimulus.js. 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 Admin Dashboard comes with a few 3rd party JavaScript libraries already included. Main libraries we’re using:

Stimulus.js
Turbo
EasyPick (date picker)
TomSelect (autocomplete/dropdowns)
Sortable.js - sortable drag and drop lists
Uppy - file uploader

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.

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:

bin/importmap pin react

This will install the dependencies, download the files to your vendor/javascript directory and add them to your config/importmap.rb file, eg.

pin "react" # @19.1.0

Now you can just import the library in your application entry point, eg. application.js:

import "react";

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 Admin Dashboard, 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 Admin Dashboard. Admin Dashboard controllers can be found in the Spree repository in the Admin Dashboard/app/javascript/spree/admin/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.

// app/javascript/controllers/hello_controller.js
import { Controller } from '@hotwired/stimulus'

export default class extends Controller {
  connect() {
    console.log("Hello Spree Commerce Stimulus!", this.element);
  }
}

To use the controller in your HTML you need to add the data-controller attribute to your element, eg.

<div data-controller="hello">
  Hello Spree Commerce Stimulus!
</div>

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.

Spree 5.2+
Spree 5.1 and below

config/initializers/spree.rb

Rails.application.config.after_initialize do
  Spree.admin.partials.head << 'spree/admin/shared/my_tracking_code'
end

config/initializers/spree.rb

Rails.application.config.spree_admin.head_partials << 'spree/admin/shared/my_tracking_code'

Creating a new partial file app/views/spree/admin/shared/_my_tracking_code.html.erb (note the leading underscore — it’s rendered as a partial), where you can add your tracking code, eg.
app/views/spree/admin/shared/_my_tracking_code.html.erb
<script> console.log("I'm a spy!"); </script>

Tutorial

Admin Panel

Customization Reference

Extending Admin Dashboard with JavaScript

3rd party JavaScript libraries

Managing JavaScript dependencies

Install dependencies

Application entry point

Stimulus Controllers

JavaScript snippets

​Extending Admin Dashboard with JavaScript

​3rd party JavaScript libraries

​Managing JavaScript dependencies

​Install dependencies

​Application entry point

​Stimulus Controllers

​JavaScript snippets

Extending Admin Dashboard with JavaScript

3rd party JavaScript libraries

Managing JavaScript dependencies

Install dependencies

Application entry point

Stimulus Controllers

JavaScript snippets