Uploading content, React, GraphQL, Rails and Active Storage
In this tutorial, we will run through how to upload some data including an image using React and GraphQL, to a Rails backend server with Active Storage.
There are some great blog posts out there on all these topics but I found a lot to be out of date. The versions I’m using are below.
To start off with we will set up our backend rails server to accept GraphQL requests. Assuming you have a rails application already set up (if not details can be found here), we first need to add graphql to our project.
Once installed it will create an app/graphql folder that contains two directories, one for mutations, and one for types. We will go over more about those later. First, we will create our model so we have something to add to the database.
We are going to create a simple Event model with three properties, name, date, and image. As the image will be handled by Active Storage, we can go ahead and create a model with those two fields for name and date.
The image will be stored in the database using a tool called Active Storage. Active storage will allow us to store attachments to active record objects and then facilitate uploading those files to the cloud. For development purposes, the files will just be stored locally.
To install Active Storage first run
Once the tables have been created we are ready to modify our model.
In our Event model, we have added three new lines. First of all, we want to create an attachment to an Active Storage object. To do this we add the has_one_attached flag to our image property. The next two lines just verify that name and start_date must be present in all event entries. With our model in place, we are now ready to add types and mutations to our GraphQL backend.
As mentioned earlier a new folder was added to the project when we added graphql. This is where we will do the rest of the backend work.
To start off with we are going to create a new type that will be used in the query and mutation requests. Below is a GraphQL query which will fetch a list of all our events.
This request called events will return the id, name, startDate, and imageUrl from our event type. To translate this into Rails we need to add a new query type.
There are a few things going on here so I will go through them all. The first thing to notice is that we are calling this type EventType which has to match up to the filename. We then declare all the fields that can be used on this type. In our case, we supply four fields, id, name, start_date, and image_url. Notice these have to match up in the GraphQL query with the snake_case fields converted to camel case. After the names, we declare the field types. For start_date we want to return a date in ISO 8601 format so we use the GrapQL built-in type ISO8601DateTime. Finally, we supply a boolean value which states if the field can be null or not.
You might be wondering how the EventType ends up being converted into our Event model. Well, once we add a new field to the QueryType we will supply a function to fetch the model objects and pass them into the EventType. This then exposes an object property that we can use in the EventType to modify what is returned from the query. This is exactly what we are going to do for the image_url. As we don’t store the image_url directly on our Event model we need to fetch it from Active Storage. To do this we override the image_url by supplying a new function.
In our new image_url function we are going to first check if an image is present on our event. If it is, we then grab the path to the image using a url_heplers function rails_blob_path which will return the path to the image. Notice we also need to include the helper at the top.
That’s it for our EventType, we now need to add the events query inside QueryType.
The QueryType is the first entry point for our GraphQL request. Here we can declare all the different query types we want. For our example, we just want to return a list of events. For that, we need to add just one field, which must match the GraphQL query name. In our case, we have called it events. We also supply a type for our field, which is an array of EventTypes, and also a boolean which states if it can be null or not.
Finally, we need to fetch our event models for our query. To do that we create an events function and just return all the events in our database. As we want the Active Storage data as well, we need to fetch all the events with the attached image.
Congratulations we now have a fully working query setup in Rails using GraphQL.
If we run this query we will see a list of all the events that we have currently stored in the database.
One small problem. We don’t have any entries in the database yet. To create new entries we will need to create a new GraphQL mutation.
To add objects to our database we will need to create a GraphQL mutation. Not only that but as we are uploading an image, we will need to leverage some third-party libraries to help us out.
For GraphQL requests, we are going to use a tool called Apollo. When it comes to queries and simple requests Apollo has everything we need. However, once we start uploading files we need a little more help. To upload an image we will have to create a multipart request so we can upload the file along with the other data. To do that we need to use a gem called Apollo Upload Server. So let’s go ahead and install that.
Once we have added the gem we can go ahead and start creating our mutation.
We start off by declaring the arguments our mutation will take. We want to upload a name and a date, both as strings. We also want an image which is of type ApolloUploadServer::Upload. This type is from the Apollo upload server and will do all the work of parsing the multipart request and return us a file we can use. Next, we need to add a resolve function to create our event.
We’re also going to declare the fields that can be returned in our GraphQL mutation request.
The first field is going to be our EventType that we made earlier. If the request is successful an event will be returned. The second field is our errors, which will return any errors generated from saving our event object. Like the query, these two field names need to match the names given in the mutation. We will look at what the raw mutation request looks like very shortly.
Finally, we create a resolve function that takes in our data from the GraphQL request and creates a new event object. For the image, we need to create an attachment so that it can be linked to the model in Active Storage. To create the attachment we use ActiveStorage::Blob.create_and_upload! to generate a blob from the file we have imported, and then pass it into our event. Once the object has been saved we assign it to our event field so that it can be returned in the GraphQL request.
Before we can test it out we just need to add a field to our MutationType.
Like our QueryType, this will be our entry point for the mutation. We call it add_event and set the type to the mutation we just created called AddEvent.
We are ready to go! We can finally try out our new API and see event entries being added to the database.
To test our addEvent mutation will need to send a POST request using multipart. I’m using Insomnia but feel free to use any rest client that supports multipart requests.
Here we can see that the request is a success and a new event has been added. Let’s break this down to see exactly what is going on.
We need to send three parts in the multipart fields to get this request to work. The first one is the operations, which is a raw string of the GraphQL request.
In this string, we supply a query and some variables. The query part is the GraphQL mutation, which when formatted, looks like this.
Here we can see more clearly exactly what we need to pass in. We first say it is a mutation and pass in the three types we need. The image is of type Upload which will match the Upload type from the Apollo upload server. Next, we call the add_event mutation which we created earlier. Remember snake_case is converted to camel case in GraphQL so that is why it looks a little different. After that, we supply the input values, which in our case is the name, startDate, and image. Finally, we supply the return values, similar to the query.
The final part of the operation is the variables, which is a hash of all the variables we are including in the request. Notice image is set to null as that will be included in a separate part of the request.
The second part of the multipart request is the map field.
Here we provide the name of all files that are going to be uploaded. The key is the name of the final part and the value is the name of the variable we declared in the operations field.
The final part of the request is the actual file we want to pass in. The name has to match the key in the map field. We can attach any file, in this case, we have passed in an image called profile.jpeg.
Congrats on getting this far. We now have a complete backend system set up to handle our GraphQL requests. The next step is to link it up with our React frontend.
To facilitate the GraphQL requests we are going to use a very popular framework called Apollo.
Before we start writing our components we are first going to set up Apollo and the Apollo upload client, which will handle the GraphQL requests and file upload.
Assuming we have a React project already set up we are first going to set up our apolloClient.
We just have some boilerplate code here for our Apollo client. We need to make sure we add the correct URL. In this case, we are running on port 3001 as our react instance will be running on port 3000.
To pass in the client we will need to inject it into our root index.js.
Here we pass in our client we created before as part of the ApolloProvider prop. This will give us access to the client when we use the useMutation hook later on.
We can now create some components. The first will allow us to drop a file on the page ready to be submitted. We are going to use a third-party library called react-dropzone for this, so let’s add it.
Next, we can add some code for our Dropzone component.
Here we are creating a styled Dropzone component that will display the name of the file that has been imported as shown below.
We are exposing a handleFile function which can be imported through our component’s props.
We now need to write another component that will use our Dropzone component.
So here we have our CreateEvent component which will use the mutation request to add an event to our database. We just have a simple input form that exposes a name, date, and file through the Dropzone component we created earlier.
Notice we are using the useMutation hook which is provided through the Apollo client to fetch our mutation. We can now go ahead and create that mutation.
This should look familiar as this is the same mutation that we added to the query section of the multipart request.
We then call the function returned from the mutation hook, and pass in the variables that it needs, which in our case is the name, date, and image file.
And there we have it, our frontend will now create an event using the name, date, and image, by sending the data using GraphQL to our Rails backend. We can check the request was successful by looking at the logs from our Rails server, or by running our events query and see the newly created fields.
Bonus: Try and create a list in React showing all of the events that have been added to the database. You will need to use the GrapgQL query we setup earlier.