☝️ GraphQL File Uploads with Apollo Server 2, React Hooks, TypeScript & Amazon S3 [Tutorial]


<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p><strong>Update: May 2022</strong><br>For our recommendation on how to handle file uploads, read <a href="https://www.apollographql.com/blog/apollo-server-file-upload-best-practices-1e7f24cdc050">Apollo Server File Uploads Best Practices</a>.</p><p>Our current recommendation is to <strong>not</strong> use the multipart request approach described in this package. In fact, this feature was removed from Apollo Server in version 3, although you can still manually integrate with the <code>graphql-upload</code> package if you take care to <a href="https://www.apollographql.com/docs/apollo-server/security/cors/#preventing-cross-site-request-forgery-csrf">protect yourself from Cross-Site Request Forgery (CSRF) attacks</a>.</p></blockquote>



<p>In web applications, one of the most common requirements is file uploads. For a while now, the question being asked around the GraphQL community is&nbsp;<strong>“How does one perform file uploads in GraphQL itself?”&nbsp;</strong>The community turned to the GraphQL specification and reference implementation but found no answers because the specification has no provisions for file uploads.</p>



<p>There are several ways you could upload files when using a GraphQL API, for example sending the file to Cloudinary or S3 directly and passing the returned URL through a GraphQL mutation. However, coordinating these multiple requests might be hard to manage. One of the simplest ways of achieving file uploads in a single request is to base64-encode a file and send as a string variable in a mutation. Another option is to send file(s) in the same request as your mutation, which I’ll cover in this post!</p>



<p><a href="https://medium.com/u/5bd1b4d20a6d?source=post_page-----5db2f3f60675----------------------" target="_blank" rel="noreferrer noopener">Jayden Seric</a>, a JavaScript engineer and GraphQL community member came up with a&nbsp;<a href="https://github.com/jaydenseric/graphql-multipart-request-spec" target="_blank" rel="noreferrer noopener">specification for GraphQL multipart form requests(file uploads)</a>&nbsp;and also provided a reference implementation.</p>



<p>At Apollo, we are committed to making sure you have the best developer experience throughout your GraphQL journey.</p>



<p>We decided to incorporate the much requested file uploads feature into&nbsp;<strong>Apollo Server 2.0</strong>, thanks to inspiration from the wonderful&nbsp;<a href="https://github.com/jaydenseric/apollo-upload-server" target="_blank" rel="noreferrer noopener">apollo-upload-server</a>&nbsp;package by Jayden. With GraphQL, we are achieving a single paradigm of data management. Just how Apollo Client merges remote and local data. Apollo Server enables you to combine multiple previously orthogonal data sources into a single paradigm. This post being about the specific case of file uploads and JSON data.</p>



<h2 class="wp-block-heading" id="312e"><a href="#how-it-works" aria-hidden="true" class="aal_anchor" id="how-it-works"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>How it works</h2>



<p>The upload functionality follows the GraphQL multipart form requests specification. Two parts are needed to make the upload work correctly. The server and the client:</p>



<p><strong>The Client:&nbsp;</strong>On the client, file objects are mapped into a mutation and sent to the server in a multipart request.</p>



<p><strong>The Server:&nbsp;</strong>The multipart request is received. The server processes it and provides an upload argument to a resolver. In the resolver function, the upload promise resolves an object.</p>



<p>Stay with me! The resolver section will reveal what the object contains and how you can use it.</p>



<h2 class="wp-block-heading" id="9bde"><a href="#server-configuration" aria-hidden="true" class="aal_anchor" id="server-configuration"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Server Configuration</h2>



<p>The default option for enabling file uploads in Apollo Server 2.0 involves creating a schema and using the&nbsp;<code>Upload</code>&nbsp;type like so:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">const { ApolloServer, gql } = require(&#039;apollo-server&#039;);

const typeDefs = gql`
  type File {
    filename: String!
    mimetype: String!
    encoding: String!
  }
  type Query {
    uploads: [File]
  }
  type Mutation {
    singleUpload(file: Upload!): File!
  }
`;</code></pre>



<p>The first question you’re most likely to ask from the schema observation above is “Where does&nbsp;<code>Upload</code>&nbsp;scalar type come from?” Don’t fret. It is added automatically by Apollo Server.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>Apollo Server 2.0 automatically adds the&nbsp;<code>Upload</code>&nbsp;scalar to the schema, when you are not setting the schema manually.</p></blockquote>



<h3 class="wp-block-heading" id="8103"><a href="#resolver-implementation" aria-hidden="true" class="aal_anchor" id="resolver-implementation"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Resolver implementation</h3>



<p>Earlier on, I mentioned that the server returns an upload promise that resolves an object. The object contains the following:</p>



<ol class="wp-block-list"><li><em>stream:</em>&nbsp;The upload stream manages&nbsp;<a rel="noreferrer noopener" href="https://nodejs.org/api/stream.html" target="_blank">streaming the file(s)</a>&nbsp;to a filesystem or any storage location of your choice. e.g. S3, Azure, Cloudinary, e.t.c.</li><li><em>filename:</em>&nbsp;The name of the uploaded file(s).</li><li><em>mimetype:&nbsp;</em>The MIME type of the file(s) such as&nbsp;<code>text/plain</code>,&nbsp;<code>application/octet-stream</code>, etc.</li><li><em>encoding:&nbsp;</em>The file encoding such as UTF-8.</li></ol>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">const resolvers = {
  Query: {
    files: () =&gt; {
      // Return the record of files uploaded from your DB or API or filesystem.
    }
  },
  Mutation: {
    async singleUpload(parent, { file }) {
      const { stream, filename, mimetype, encoding } = await file;

      // 1. Validate file metadata.

      // 2. Stream file contents into cloud storage:
      // https://nodejs.org/api/stream.html

      // 3. Record the file upload in your DB.
      // const id = await recordFile( … )

      return { filename, mimetype, encoding };
    }
  },
};</code></pre>



<p>In the code above, the file can be validated after the promise resolves. If the file size or type is right (depending on the validation technique), it can be streamed into cloud storage like&nbsp;<a href="https://cloudinary.com/documentation/node_image_upload" target="_blank" rel="noreferrer noopener">Cloudinary</a>&nbsp;and the returned link can be stored in a database. Otherwise an&nbsp;<a href="https://dev-blog.apollodata.com/full-stack-error-handling-with-graphql-apollo-5c12da407210" target="_blank" rel="noreferrer noopener">Apollo error can be thrown</a>&nbsp;within the resolver.</p>



<h2 class="wp-block-heading" id="615d"><a href="#client-setup" aria-hidden="true" class="aal_anchor" id="client-setup"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Client Setup</h2>



<p>If the user is expected to upload files from an interactive client UI, then you need to install the&nbsp;<code>apollo-upload-client</code>&nbsp;package from npm. And deal with single and multiple files from the client.</p>



<p><em>Single file upload example from the client:</em></p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">import gql from &#039;graphql-tag&#039;
import { Mutation } from &#039;react-apollo&#039;

export const UPLOAD_FILE = gql`
  mutation uploadFile($file: Upload!) {
    uploadFile(file: $file) {
      filename
    }
  }
`;

const uploadOneFile = () =&gt; {
  return (   
    &lt;Mutation mutation={UPLOAD_FILE}&gt;
      {uploadFile =&gt; (
        &lt;input
        type=&quot;file&quot;
        required
        onChange={({ target: { validity, files: [file] } }) =&gt;
          validity.valid &amp;&amp; uploadFile({ variables: { file } });
        }
       /&gt;
      )}
    &lt;/Mutation&gt;
  );
};</code></pre>



<p>Use&nbsp;<code>&lt;a href=&quot;https://developer.mozilla.org/en/docs/Web/API/FileList&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;FileList&lt;/a&gt;</code>,&nbsp;<code>&lt;a href=&quot;https://developer.mozilla.org/en/docs/Web/API/File&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;File&lt;/a&gt;</code>,&nbsp;<code>&lt;a href=&quot;https://developer.mozilla.org/en/docs/Web/API/Blob&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;Blob&lt;/a&gt;</code>&nbsp;or&nbsp;<code>&lt;a href=&quot;https://github.com/jaydenseric/apollo-upload-client#react-native&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;ReactNativeFile&lt;/a&gt;</code>&nbsp;instances anywhere within query or mutation input variables to send a&nbsp;<a href="https://github.com/jaydenseric/graphql-multipart-request-spec" target="_blank" rel="noreferrer noopener">GraphQL multipart request</a>. In the example above, we operated a single file upload, thus using&nbsp;<code>&lt;a href=&quot;https://developer.mozilla.org/en/docs/Web/API/File&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;File&lt;/a&gt;</code><code>.</code></p>



<p>The user selects a file, the client validates the file and immediately sends a multipart request in the same request as the&nbsp;<code>uploadFile</code>&nbsp;mutation to the server.</p>



<p>Check out the&nbsp;<a href="https://www.apollographql.com/docs/guides/file-uploads.html" target="_blank" rel="noreferrer noopener">file uploads documentation for more information on multiple and blob file uploads from the client.</a></p>



<h2 class="wp-block-heading" id="9a10"><a href="#try-it-out" aria-hidden="true" class="aal_anchor" id="try-it-out"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Try it out</h2>



<p>A&nbsp;<a href="https://github.com/jaydenseric/apollo-upload-examples" target="_blank" rel="noreferrer noopener">full-stack working example created by Jayden is available on GitHub</a>. Clone and try it out. Feel free to provide feedback.</p>



<p>To keep learning, check out our<a href="https://www.apollographql.com/docs/" target="_blank" rel="noreferrer noopener">&nbsp;new best practices guides about topics like schema design, versioning, access control, and more.</a></p>



<hr class="wp-block-separator"/>



<p>Finally, I hope you’ll also&nbsp;<a href="https://summit.graphql.com/" target="_blank" rel="noreferrer noopener">join us at the 3rd annual GraphQL Summit on Nov 7–8 in San Francisco</a>. With over 800 attendees expected, it’s the largest GraphQL developer event in the world. Super early bird tickets are selling fast, so&nbsp;<a href="https://www.eventbrite.com/e/graphql-summit-2018-tickets-46601841362" target="_blank" rel="noreferrer noopener">register today</a>&nbsp;to reserve your spot!</p>


File Uploads

☝️ GraphQL File Uploads with Apollo Server 2, React Hooks, TypeScript & Amazon S3 [Tutorial]

File Uploads with Apollo Server 2.0

Stay in our orbit