Introducing the New Filestack::Rails Plugin

Richard HerbertProduct Updates1 Comment

We’ve got lots of exciting stuff going on at Filestack right now, including a new release of our File Picker; brand new SDKs in Python, PHP and Ruby; and an update to one of our most popular plugins: Filestack::Rails.

Formerly known as Filepicker::Rails, the plugin now includes v3 of our File Picker and adds support for Rails 4 and 5. It also harnesses the power of our Ruby SDK, new and improved uploads, and has full access to all of our image transformation options through our Transformation Engine. Many common issues and suggestions have been addressed, and now integrating Filestack into your Rails application has never been easier.


For this tutorial, I will assume that you have either Rails 4 or 5 installed (I will be using 5.x) and a general knowledge of how to work in the framework (as well as in Ruby). If you don’t, nothing here should be too difficult, and could even be a good introduction to the pipeline.

First, let’s create a new project:

$ rails new filestack-tutorial

Navigate to the project directory and add the following to your Gemfile:

gem 'filestack-rails', require: 'filestack-rails'

This installs the Filestack::Rails plugin and injects it into your project for use. Now bundle install and you’re ready to roll (Note: If you have a previous version of Filestack::Rails or Filepicker::Rails installed, you will need to also run bundle update).

Defining the User Scaffold

Rails scaffolds allow to you dynamically create the model, views and controllers necessary for different kinds of website-database interaction. For this tutorial, all we want to do is allow a user to create a basic profile, including their name, their email address, and a profile picture. This is easily achieved like so:

$ rails generate scaffold User nameL:string email:string picture:string

The scaffold command generates everything necessary for model creation, editing and destruction, including navigation. Before testing, though, you will have to migrate your changes to the database:

$ rails db:migrate

Spin up the server and make sure everything is working as planned at localhost:3000:

$ rails server


Integrating Filestack

Now that the boilerplate is out of the way, let’s go ahead and get Filestack integrated. If you don’t already have an API key, you can get one here. Sign up for the free membership to get started, and be sure to check out the different kinds of plans we have for developers and businesses of every size.

To set up the plugin, you need to add your API key to the config/application.rb, like this:

config.filestack_rails.api_key = 'YOUR_API_KEY'

Once this is done, go to app/views/layouts/application.html.erb and add the following two lines between the HEAD tags:

<%= filestack_js_include_tag %>
<%= filestack_js_init_tag %>

Filestack::Rails works by injecting our File Picker and Web SDK into your client-side Javascript. While this defaults in name to “filestack_client” and therefore shouldn’t interfere with any of your code, you do have the ability to control the name of the client via an additional line to the config file:

config.filestack_rails.client_name = 'custom_client'

If you ran your application and then typed the following into your browser console,


you should see the Picker object. You can set the client name to anything you like, and also have direct access to the Picker and Web SDK through any of your own Javascript assets, presuming you add them after the Filestack tags.

Adding the Picker

Navigate to app/views/users/_form.html.erb. You should see something like the following:

<div class="field">

  <%= form.label :picture %>

  <%= form.text_field :picture, id: :user_picture %>


Change it to this:

<div class="field">

  <%= form.label :picture %>

  <%= form.filestack_field :picture, 'Upload Your Avatar' %>


Then navigate to app/views/user/show.html.erb, and find these lines:



  <%=@user.picture %>

Change them to:


  <%= filestack_image @user.picture, transform: filestack_transform.resize(width: 100, height: 100) %>


A couple of things are going on here. First, we have added the filestack_field form helper, which functions very similarly to the previous versions’, as it adds a button and a hidden text field that will display whatever text you pass in the second argument, open the Picker when clicked, and automatically attach the value of the returned file to your form.

Secondly, in our users/show HTML file, we have replaced the Rails auto-generated text field with a filestack_image tag, which takes as a first argument the url of the image you would like to display, and then all other Rails image tag options, including an additional “transform” parameter, into which you can pass a filestack_transform chain.

Now, if you run rails server, navigate to localhost:3000/users, click to create a new user and you should be able to do the following:

That’s it! Integrating Filestack::Rails into your application takes only a few minutes and minimal code to get up and running. To find out more about the plugin and its functionality, including a migration guide from 2.x to 3.x, check out the GitHub repository and README, and be sure to stay posted on exciting, future updates from the Filestack team.