Solidus
Search…
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.
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 images:
    mini: 48x48
    small: 400x400
    product: 680x680
    large: 1200x1200
You can access the URL for a specific sizes by calling, e.g. Spree::Image#url:
1
image = Spree::Image.first
2
image.url(:product)
Copied!
If you're building a custom storefront, you may also want to change the sizes of the images in your store. You can do this by applying an override to Spree::Image:
app/overrides/amazing_store/spree/image/customize_sizes.rb
1
module AmazingStore
2
module Spree
3
module Image
4
module CustomizeSizes
5
def self.prepended(klass)
6
klass.attachment_definitions[:attachment][:styles] = {
7
mini: '48x48>',
8
small: '400x400>',
9
product: '680x680>',
10
large: '1200x1200>',
11
jumbo: '1600x1600>'
12
}
13
end
14
15
::Spree::Image.prepend self
16
end
17
end
18
end
19
end
Copied!
Now that you changed your sizes, try getting the URL for your new jumbo size or large sizes:
1
image = Spree::Image.first
2
image.url(:jumbo)
3
taxon = Spree::Taxon.first
4
taxon.url(:large)
Copied!
Solidus will generate the new sizes and return their URLs!
You can also use your new styles in the image partial:
1
<%= render 'spree/admin/shared/image', image: product.gallery.images.first, size: :jumbo %>
Copied!

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
1
Spree.config do |config|
2
# ...
3
4
config.allowed_image_mime_types = %w(image/jpeg image/jpg image/png image/gif image/webp).freeze
5
end
Copied!

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.
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
1
module AmazingStore
2
module ImageAttachment
3
# ...
4
end
5
end
Copied!
Once you have your custom attachment module, you need to tell Solidus to use it:
config/initializers/spree.rb
1
Spree.config do |config|
2
# ...
3
config.image_attachment_module = 'AmazingStore::ImageAttachment'
4
end
Copied!
To replace the taxon attachment, follow the same process, but set the taxon_attachment_module configuration option instead.
Last modified 3mo ago