CarrierWave

CarrierWave
Name	CarrierWave
Title	CarrierWave
Developer	Shrining, GitHub
Released	2009
Programming language	Ruby (programming language), RubyGems
Operating system	Unix, Linux, macOS, Windows
License	MIT License

CarrierWave is a file uploading library for Ruby (programming language) and the Ruby on Rails web application framework. It provides an uploader abstraction that integrates with storage backends such as Amazon S3, Google Cloud Storage, and local filesystem adapters to manage uploads for models used in applications like GitHub, Basecamp, Shopify, and Airbnb. The library is maintained on GitHub and has been used alongside gems and tools from the RubyGems ecosystem, influenced by patterns seen in projects such as Paperclip (software) and Refile (gem).

History

CarrierWave was created in the late 2000s to address file upload needs within the Ruby on Rails community and to provide a lighter, more flexible alternative to existing solutions used by teams at 37signals and contributors active around RailsConf. Early adopters included developers from projects associated with Heroku and Engine Yard, who required pluggable backends like Amazon S3 and integration with content delivery networks such as CloudFront. Over time, CarrierWave evolved in parallel with shifts in deployment patterns influenced by Docker, Capistrano, and the rise of cloud services like Google Cloud Platform and Microsoft Azure. Maintenance and contributions have come through GitHub issues and pull requests involving maintainers familiar with RSpec, Minitest, and continuous integration platforms like Travis CI and CircleCI.

Features

CarrierWave offers features that support typical Rails app requirements, mirroring considerations seen in libraries used by Basecamp, Shopify, and GitLab. Key features include processing hooks compatible with image tools such as ImageMagick and MiniMagick, storage adapters for Amazon S3, Google Cloud Storage, and local filesystems, and integrations enabling background processing through Sidekiq, Resque, and Active Job. Upload lifecycle callbacks align with patterns used in ActiveRecord and Sequel (software), while thumbnailing, versioning, and caching workflows draw on approaches first codified in projects like Paperclip (software) and CarrierWave-adjacent utilities. Security and validation hooks are compatible with authentication systems such as Devise and authorization libraries like Pundit and CanCanCan.

Architecture and Components

CarrierWave's architecture centers on uploader classes that act as adapters between model attributes and storage backends, a design pattern also found in systems developed at Twitter and Facebook. Uploader classes declare processing pipelines using processors that can invoke external binaries like ImageMagick or libraries such as Ruby Vips. Storage engines implement interfaces for persistence to services including Amazon S3, Google Cloud Storage, Microsoft Azure Storage, and the local filesystem. Integration points map to ORMs like ActiveRecord, Sequel (software), and Mongoid, enabling attachment semantics similar to those in projects such as Diaspora (social network) and Spree (e-commerce platform). Background processing integration uses job runners like Sidekiq, Resque, Delayed Job, and orchestration tools exemplified by Kubernetes deployments.

Usage and Examples

Typical usage involves generating an uploader class in a Ruby on Rails application and mounting it on a model backed by ActiveRecord or Mongoid. Examples in the wild show patterns used by applications comparable to Shopify storefronts or GitLab repositories: defining versions for thumbnails, invoking MiniMagick for resizing, and configuring adapters for Amazon S3 with credentials managed by services like Vault (software) or environment tooling from Heroku. Tests commonly rely on RSpec fixtures and stubbing libraries used in projects such as RSpec Rails and Factory Bot. Deployment examples mirror strategies from Capistrano and container workflows from Docker and Kubernetes.

Configuration and Upload Process

Configuration is typically placed in initializer files in Ruby on Rails projects, aligning with conventions used in applications like Basecamp and GitLab. Settings specify storage backends—Fog (library) historically provided multi-provider support to services such as Amazon S3, Google Cloud Storage, and Rackspace Cloud Files—and processing options that call into ImageMagick or Vips. The upload process follows a lifecycle: assignment in model forms used with Action Pack controllers, temporary caching that mirrors practices in Paperclip (software), processing for versions and transformations, and final storage to backends with optional backgrounding through Active Job adapters for Sidekiq or Resque. Credential management patterns draw from 12-factor app principles embraced by Heroku and Cloud Foundry deployments.

Integrations and Ecosystem

CarrierWave integrates with a broad Ruby ecosystem: ORMs like ActiveRecord and Mongoid (Ruby ODM), job systems such as Sidekiq and Resque, image processing libraries like MiniMagick and ruby-vips, and storage adapters powered by Fog (library), fog-aws, and native SDKs for Amazon S3, Google Cloud Storage, and Microsoft Azure. It is often compared or used alongside alternatives and complementary projects such as Paperclip (software), Shrine (gem), Refile (gem), and asset management tools like Webpack and Sprockets. Community contributions and discussions have taken place on GitHub and in forums frequented by developers from organizations like Thoughtbot, Stripe, and Etsy.

Category:Ruby libraries