Images Customization

Overview

This guide explains how to change Product Images dimensions and different storage options for both ActiveStorage and Paperclip.

ActiveStorage

ActiveStorage is the default attachment storage system since Spree 3.6 and Rails 5.2. To read more about ActiveStorage head to the official documentation.

Image dimensions

To change the default image dimensions or add new ones you need to create a decorator file app/models/my_store/spree/image_decorator.rb:

module MyStore
  module Spree
    module ImageDecorator
      module ClassMethods
        def styles
          {
            mini:    '48x48>',
            small:   '100x100>',
            product: '240x240>',
            large:   '600x600>',
          }
        end
      end

      def self.prepended(base)
        base.inheritance_column = nil
        base.singleton_class.prepend ClassMethods
      end
    end
  end
end

::Spree::Image.prepend ::MyStore::Spree::ImageDecorator

You can also create image variations on the fly in your templates, eg.

<%= image_tag(main_app.url_for(@product.images.first.attachment.variant(resize: '150x150'))) %>

Using Amazon S3 as storage system

Please refer to the official Active Storage documentation

You can also use Microsoft Azure Storage or Google Cloud Storage

Paperclip

Paperclip support was removed in Spree 4.0. To migrate to ActiveStorage please read the official migration guide.

Image dimensions

Until Spree 3.6 we’ve used Thoughtbot’s paperclip gem to manage images for products. All the normal paperclip options are available on the Image class. If you want to modify the default Spree product and thumbnail image sizes, simply create an app/models/spree/image_decorator.rb file and override the attachment sizes:

Spree::Image.class_eval do
  attachment_definitions[:attachment][:styles] = {
    mini: '48x48>', # thumbs under image
    small: '100x100>', # images on category view
    product: '240x240>', # full product image
    large: '600x600>' # light box image
  }
end

You may also add additional image sizes for use in your templates (:micro for shopping cart view, for example).

Image resizing option syntax

Default behavior is to resize the image and maintain aspect ratio (i.e. the :product version of a 480x400 image will be 240x200). Some commonly used options are:

• trailing #, image will be centrally cropped, ensuring the requested dimensions
• trailing >, image will only be modified if it is currently larger than the requested dimensions. (i.e. the :small thumb for a 100x100 original image will be unchanged)

Using Amazon S3 as storage system

Start with adding AWS-SDK to your Gemfile with: gem 'aws-sdk-s3', then install the gem by running bundle install.

When that’s done you need to configure Spree to use Amazon S3. You can add an initializer or just use the spree.rb initializer located at config/intializers/spree.rb.

attachment_config = {
  s3_credentials: {
    access_key_id:     ENV['AWS_ACCESS_KEY_ID'],
    secret_access_key: ENV['AWS_SECRET_ACCESS_KEY'],
    bucket:            ENV['S3_BUCKET_NAME']
  },

  storage:        :s3,
  s3_region:      ENV['S3_REGION'],
  s3_headers:     { "Cache-Control" => "max-age=31557600" },
  s3_protocol:    "https",
  bucket:         ENV['S3_BUCKET_NAME'],
  url:            ":s3_domain_url",

  path:           "/:class/:id/:style/:basename.:extension",
  default_url:    "/:class/:id/:style/:basename.:extension",
}

attachment_config.each do |key, value|
  Spree::Image.attachment_definitions[:attachment][key.to_sym] = value
end

Note that I use the url: ":s3_domain_url" setting, this enabled the DNS lookup for your images without specifying the specific zone endpoint. You need to use a bucket name that makes a valid subdomain. So do not use dots if you are planning on using the DNS lookup config.