Shrine Documentation

When transitioning from Paperclip to Shrine, note these fundamental architectural shifts:

• Uploader Logic: Paperclip configures attachments directly in models. Shrine encapsulates logic in dedicated Uploader classes.
• Storage: Paperclip couples storage configuration to the model. Shrine uses decoupled Shrine.storages objects and supports a concept of 'temporary' (cache) storage.
• Persistence: Paperclip uses multiple columns (_file_name, _content_type, etc.). Shrine uses a single <name>_data column containing a JSON object with id, storage, and metadata.
• Location: Paperclip stores only the filename and calculates paths dynamically. Shrine persists the full location in the JSON data, making it more resilient to configuration changes.
• Processing: Paperclip uses model-level styles. Shrine uses instance-level processing (e.g., via the derivatives plugin), allowing for more control and agnostic processing tools (like libvips via image_processing).

Shrine does not have a direct attachment_field helper. Instead, use the cached_attachment_data plugin and manually render hidden fields for the cached data alongside a standard file field.

Replace attachment_field

Refile:

form_for @user do |form|
  form.attachment_field :profile_image
end

Shrine:

Shrine.plugin :cached_attachment_data

form_for @user do |form|
  form.hidden_field :profile_image, value: @user.cached_profile_image_data, id: nil
  form.file_field :profile_image
end

Replace remove_<attachment>

Use the remove_attachment plugin to add a removal method to your model.

Refile: (Uses remove_<attachment> method)

Shrine:

Shrine.plugin :remove_attachment

form_for @user do |form|
  form.hidden_field :profile_image, value: @user.cached_profile_image_data, id: nil
  form.file_field :profile_image
  form.check_box :remove_profile_image
end

Replace remote_<attachment>_url

Use the remote_url plugin to add the #<attachment>_remote_url method to your model.

Refile: (Uses remote_<attachment>_url method)

Shrine:

Shrine.plugin :remote_url

form_for @user do |form|
  form.hidden_field :profile_image, value: @user.cached_profile_image_data, id: nil
  form.file_field :profile_image
  form.text_field :profile_image_remote_url
end

# Example of replacing attachment_field with Shrine
Shrine.plugin :cached_attachment_data

form_for @user do |form|
  form.hidden_field :profile_image, value: @user.cached_profile_image_data, id: nil
  form.file_field :profile_image
end

To use backgrounding, you must define background jobs (e.g., using Sidekiq) and register them using Shrine::Attacher.promote_block and Shrine::Attacher.destroy_block.

Global Configuration

Register blocks globally in your initializer to apply to all uploaders:

Shrine::Attacher.promote_block do
  PromoteJob.perform_async(self.class.name, record.class.name, record.id, name.to_s, file_data)
end

Shrine::Attacher.destroy_block do
  DestroyJob.perform_async(self.class.name, data)
end

Uploader-Specific Configuration

Alternatively, you can define these blocks within a specific uploader class:

class MyUploader < Shrine
  Attacher.promote_block do
    PromoteJob.perform_async(self.class.name, record.class.name, record.id, name.to_s, file_data)
  end

  Attacher.destroy_block do
    DestroyJob.perform_async(self.class.name, data)
  end
end

# Example of a PromoteJob implementation
class PromoteJob
  include Sidekiq::Worker

  def perform(attacher_class, record_class, record_id, name, file_data)
    attacher_class = Object.const_get(attacher_class)
    record         = Object.const_get(record_class).find(record_id)

    attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
    attacher.atomic_promote
  rescue Shrine::AttachmentChanged, ActiveRecord::RecordNotFound
    # attachment has changed or record has been deleted, nothing to do
  end
end

# Example of a DestroyJob implementation
class DestroyJob
  include Sidekiq::Worker

  def perform(attacher_class, data)
    attacher_class = Object.const_get(attacher_class)

    attacher = attacher_class.from_data(data)
    attacher.destroy
  end
end