Skip to content
AlchemyCMS Solidus Integration
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
app Use spree backend config to register admin tab Sep 10, 2018
bin Add a integration spec Dec 22, 2017
config Remove Reports tab from alchemy navigation Mar 11, 2019
lib v2.3.1 May 15, 2019
spec Add Solidus admin unauthorized redirect handler Mar 11, 2019
.travis.yml Update solidus versions build matrix Mar 11, 2019 v2.3.1 May 15, 2019
Gemfile Update Gemfile matrix after Alchemy 4.1 release Mar 11, 2019

Build Status

AlchemyCMS Solidus Integration

The World's Most Flexible E-Commerce Platform meets The World's Most Flexible Content Management System!

This gem is a AlchemyCMS and Solidus connector.

For now it does this:

  1. It provides tabs in Alchemy and Solidus menus to easily switch between both backends
  2. It offers two new Essences for Alchemy called EssenceSpreeProduct and EssenceSpreeTaxon that you can use to place Spree products and/or Taxons on your pages.
  3. Shares admin sessions and user abilities between Alchemy and Solidus.



This version runs with Solidus 2.0 and above. For a Solidus 1 compatible version please use the 1.0-stable branch or 1.1.0 gem version.


This version runs with Alchemy 4.0 and above. For a Alchemy 3 compatible version please use the 1.0-stable branch or 1.1.0 gem version.


Add this line to your application's Gemfile:

gem 'alchemy-solidus', github: 'AlchemyCMS/alchemy-solidus', branch: 'master'

Install the gem with:

$ bundle install

Automated setup

We ship a Rails generator that helps you to install this gem into your existing Rails app.

$ bin/rails g alchemy:solidus:install

There are several options available, please check them by:

$ bin/rails g alchemy:solidus:install --help

Manual setup

Authentication system installation

Both Alchemy and Solidus come without an authentication system in place. You will need to choose an authentication system yourself. There are 3 available options. Whichever you choose, you need to instruct Solidus & Alchemy about your choice of authentication system.

Here are the steps for each option:

1. Option: Use Solidus Auth Devise

Recommended for:

  • An existing Solidus installation (gem 'solidus_auth_devise' should already be in your Gemfile).
  • You are just adding Alchemy

To use Solidus Auth Devise, instruct Alchemy to use the Spree::User class:

# config/initializers/alchemy.rb
Alchemy.user_class_name = 'Spree::User'
Alchemy.current_user_method = :spree_current_user

If you put Spree in it's own routing namespace (see below) you will want to let Alchemy know these paths:

# config/initializers/alchemy.rb
Alchemy.login_path = '/store/login'
Alchemy.logout_path = '/store/logout'

2. Option: Use Alchemy Devise

Recommended for:

  • An existing Alchemy installation
  • You don't have an authentication system and don't want to role an authentication system on your own.

Add alchemy-devise to your Gemfile

# Gemfile
gem 'alchemy-devise', '~> 4.1'

and install it:

$ bundle install
$ bundle exec rails g alchemy:devise:install

Run the Solidus installer:

NOTE: Skip this if you already have a running Solidus installation.

$ bundle exec rails g spree:install

Then run the solidus custom user generator:

$ bundle exec rails g spree:custom_user Alchemy::User

Now you'll need to instruct Solidus to use the Alchemy User class:

# config/initializers/spree.rb
Spree.user_class = "Alchemy::User"

and tell Solidus about Alchemy's path helpers:

# lib/spree/authentication_helpers.rb
    def spree_login_path

    def spree_signup_path

    def spree_logout_path

3. Option: Build their own authentication

Please follow the spree custom authentication and the Alchemy custom authentication guides in order to integrate your custom user with Solidus and Alchemy.

In either case

Install the migrations

$ bundle exec rake alchemy_solidus:install:migrations

Run the installer of Alchemy

$ bundle exec rake alchemy:install

and follow the on screen instructions.

Render Alchemy Content in Solidus Layout

If you plan to render the Alchemy site in the Solidus layout add the following to your initializer:

# config/initializers/alchemy.rb
require 'alchemy/solidus/use_solidus_layout'

Render Alchemy Content in Solidus views

If you plan to render Alchemy content in your Solidus views (ie. a global header or footer section), you need to include the Alchemy view helpers and language store in your Solidus controllers with the following addition to your initializer:

# config/initializers/alchemy.rb
require 'alchemy/solidus/alchemy_in_solidus'


For routing you have a few options.

Place both engines in their own namespace:

# config/routes.rb
mount Spree::Core::Engine => '/store'
mount Alchemy::Engine => '/pages'

Put Solidus at the root level and Alchemy in its own namespace:

# config/routes.rb
mount Alchemy::Engine => '/pages'
mount Spree::Core::Engine => '/'

Put Alchemy at the root level and Solidus in its own namespace:

# config/routes.rb
mount Spree::Core::Engine => '/store'
mount Alchemy::Engine => '/'

Put both engines in the root level

# config/routes.rb

# Make Alchemy's root page have higher priority than Spree's root page
root to: 'alchemy/pages#index'

mount Spree::Core::Engine => '/'

# Must be last so it's catch-all route can render undefined paths
mount Alchemy::Engine => '/'


Create a new Element for Alchemy

# config/alchemy/elements.yml
- name: product
  - name: spree_product
    type: EssenceSpreeProduct

- name: product_category
  - name: spree_taxon
    type: EssenceSpreeTaxon

Generate the views

$ rails g alchemy:elements --skip

Place this element on a page layout

# config/alchemy/page_layouts.yml
- name: product
  elements: [product]
- name: products
  elements: [product_category]

You can haz Solidus product and taxons!

# app/views/alchemy/elements/_product_view.html.erb
<%= element.ingredient('spree_product') %>

# app/views/alchemy/elements/_product_category_view.html.erb
<%= element.ingredient('spree_taxon') %>

Alchemy ❤️ Solidus!


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request
You can’t perform that action at this time.