Benjamin Willems edited this page Apr 6, 2018 · 16 revisions

What is the best way to begin learning Solidus?

Start by learning Ruby and Ruby on Rails.

Once you understand Rails, we suggest reading the solidus_core test suite. It should give you a good idea about what’s going on. Start with models, move onto controller tests, and so on.

Take notes on the associations between models so that you understand how products, variants, options, properties, and taxons are related to each other.

You should definitely do this before you start trying to model any real data.

How do I submit a Solidus extension to solidusio-contrib?

Generally we add extensions to soludusio-contrib if we can find someone to maintain it for the newest Solidus release.

We collate all of the contributed extensions at

We also want to insist that all of the solidusio-contrib extensions have good test coverage so that we know when they break.

Can I use the spree_* extension with Solidus?


Spree extensions can't be used directly with Solidus, because they will have Spree as a dependency. Since Solidus is based off of Spree 2.4, extensions can usually be updated.

Here's the usual process:

  1. You need to fork the spree extension.
  2. You need to update all dependencies from spree_* to solidus_* in the extension's .gemspec file. So spree_backend becomes solidus_backend, spree_api becomes solidus_api and so on.
  3. Make adjustments to changes between Spree 2.4 and the current version of Solidus.

The required changes depend on what parts of Solidus the extension extends. The process will involve some trial and error.

Before you start, please look at all of the repositories at solidusio and solidusio-contrib to see if someone has already done the work.

How do I upgrade from Spree-x.y?

See Upgrading from Spree

Why is it called "Solidus"?

Solidus is the name of an old Roman coin and is also the name for a forward slash. We also like the connotation of "solid" being in the name.

Why is the namespace Spree::?

The Spree:: namespace is a little confusing, but it's well worth keeping as we have good compatibility with most spree 2-4-ish extensions and with existing stores, all of which will be referencing models in the Spree namespace.

The namespace is also used for table names, and used for STI. (For example, in PaymentMethods, where the class name is stored in the database.).

This also happens in other successful forks, for example Jenkins still has a lot of classes namespaced under Hudson's namespace.

How do I customize the frontend?

Typically, people override the partials from Solidus's solidus_frontend gem. There's also the possibility of using the Deface gem to do "magic overrides", but it's usually simpler to just override whole files. If you're just starting out, this video series seems to have helped people.

I'm getting an error, "undefined mixin 'display'". What do I do?

When Bourbon hit 5.0.0, it removed a bunch of mixins that older versions of Solidus used. Check if your application uses Bourbon, and what version:

bundle show bourbon

If you're using 5.0.0 or newer, try explicitly locking the version to < 5.0.0 in your Gemfile:

gem 'bourbon', '< 5.0.0'

How to I associate my app's models with Spree::SomeModel? Or, how do change the functionality of Solidus::SomeModel?

Alas, Solidus models are stuck inside the solidus_core gem, and you can't just edit their source code. If you need to modify a class to support your custom features, you can decorate the class.

See Decorators for Solidus's recommended way to do this.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.