Image processing

Architecture overview

In a typical Solidus store, you can upload images for products and taxons.

Under the hood, Solidus will use a different file processing library depending on the Rails version: Active Storage is the default starting from Rails 6.1, while Paperclip is used in earlier versions.

caution

Active Storage cannot be used in Rails 6.0 or earlier because it doesn't support public URLs, which Solidus needs to serve images to your users. If you're on Rails 6.0 or earlier, you have to use Paperclip.

While Paperclip is deprecated and will be removed in the near future, Solidus provides a compatibility layer that abstracts the differences between the two libraries, in order to offer an easier migration path to existing Paperclip users.

Customizing image sizes

By default, Solidus uses the following sizes for product images:

• mini: 48x48
• small: 400x400
• product: 680x680
• large: 1200x1200

and the following sizes for taxon icons:

• mini: 32x32
• normal: 128x128

You can access the URL for a specific size by calling Spree::Image#url:

image = Spree::Product.first.gallery.images.first
image.url(:product)

If you're building a custom storefront, you may also want to change the sizes of the images in your store or add additional sizes. The default sizes can be changed using the Spree::Config.product_image_styles option.

For example, we can set some new defaults and introduce a new :jumbo style like this:

config/initializers/spree.rb

Spree.config do |config|
  # ...
  config.product_image_styles = {
    mini: '48x48>',
    small: '100x100>',
    product: '240x240>',
    large: '600x600>',
    jumbo: '1600x1600>'
  }
end

Similar to product styles, you can customize the taxon image styles using the Spree::Config.taxon_image_styles configuration option.

caution

Active Storage will automatically generate sizes upon initial request. If you change the default image sizes and are using Paperclip, you must regenerate the styles by running a Rake task:

bundle exec rake paperclip:refresh:thumbnails CLASS=Spree::Image

or if you are only adding new styles, you can run the following task:

bundle exec rake paperclip:refresh:missing_styles CLASS=Spree::Image

Now that you changed your sizes, try getting the URL for your new jumbo or mini sizes:

image = Spree::Product.first.gallery.images.first
image.url(:jumbo)

icon = Spree::Taxon.first.icon
icon.url(:mini)

You can also use your new styles in the image partial in the backend:

<%= render 'spree/admin/shared/image', image: product.gallery.images.first, size: :jumbo %>

and if you are using solidus_starter_frontend for your storefront like this:

<%= render(
  ImageComponent.new(
    image: product.gallery.images.first,
    size: :jumbo,
    itemprop: "image",
    data: { js: 'product-main-image' }
  )
) %>

Customizing the allowed MIME types

By default, Solidus only accepts PNG, JPEG and GIF images. If you want to accept additional MIME types, e.g. WebP, you can do it via the allowed_image_mime_types configuration option:

config/initializers/spree.rb

Spree.config do |config|
  # ...

  config.allowed_image_mime_types = %w(image/jpeg image/jpg image/png image/gif image/webp).freeze
end

Replacing an attachment module

If the change you want to apply cannot be made through the existing configuration options, you can entirely replace the product image or taxon icon attachment module with your own.

This can be useful, for example, if you need to customize your image styles or perform custom post-processing operations on your image such as watermarking, compression, etc.

info

When replacing an attachment module, we recommend copy-pasting the original module first and only changing what you need. The right starting point will depend on whether you're using ActiveStorage or Paperclip. You can find the modules for Spree::Image here and the modules for Spree::Taxon here.

Here's an example for the product image attachment:

app/models/amazing_store/image_attachment.rb

module AmazingStore
  module ImageAttachment
    # ...
  end
end

Once you have your custom attachment module, you need to tell Solidus to use it:

config/initializers/spree.rb

Spree.config do |config|
  # ...
  config.image_attachment_module = 'AmazingStore::ImageAttachment'
end

To replace the taxon attachment, follow the same process, but set the taxon_attachment_module configuration option instead.