Writing a New Solidus Extension

Sometimes building a site powered by Solidus will require customization. Solidus extensions are Rails engines that allow you to extend or change the functionality of the Solidus platform.

Find existing extensions

Before you write a new Solidus extension you should look for an existing extension that meets your needs. Solidus maintains an official list of supported extensions , but you can also use soliton to search for extensions.

There is also a series of curated extensions available under the solidus-contrib organization.

Developing a Solidus extension locally

Install the solidus_cmd gem

A Solidus extension is just a Rails engine, you can build the extension in exactly the same way you'd build any other Rails engine.

However, it is recommended that you use the solidus_cmd gem.

Bash
    
      gem install solidus_cmd

    
  

The solidus_cmd gem will generate the boilerplate Rails engine and ensure that you aren't missing any of the default dependencies.

Generate a new Solidus extension

Once you've installed solidus_cmd, you will have access to the solidus command. Using solidus extension will generate a new Solidus extension template in your current directory.

Bash
    
      solidus extension extension_name

    
  

Configure your extension

After solidus_cmd has generated your extension template, you will need to configure your gemspec file. This step of the process is similar to building any Ruby gem .

This is the right time to set the version of Solidus you are targeting with your extension. You can set that dependency and any other dependencies you anticipate in the gemspec file.

Developing your extension locally

To work on your Solidus extension locally you will need a Solidus application to host the extension. Setting up a Solidus application specifically for testing is recommended.

Loading your Solidus extension is as simple as adding it to your Gemfile.

Once you're ready to load the extension into your test Solidus application, you can add the gem to your Solidus application's Gemfile using the path option:

Ruby
    
      gem "solidus_extension_name", path: "path/to/extension"

    
  

You can now use the bundle command to install your extension.

Registering your extension

Solidus extensions benefit from being shared with the community. Sharing your extension will allow other Solidus developers to extend the functionality of your code.

You can add your extension to the official list of supported extensions by submitting a PR to solidusio/extensions.solidus.io .

Feedback

Solidus is an open source platform supported by the community. We encourage everyone using Solius to contribute back to the documentation and the code.

If you’re interested in contributing to the docs, get started with the contributing guidelines. If you see something that needs fixing and can’t do it yourself, please send us an email.