apollo-upload-client

What is apollo-upload-client?

The apollo-upload-client package is a client for Apollo GraphQL that enables file uploads via GraphQL mutations. It extends Apollo Client to support file uploads using the GraphQL multipart request specification.

What are apollo-upload-client's main functionalities?

File Upload

This feature allows you to upload files via GraphQL mutations. The code sample demonstrates how to set up an Apollo Client with the upload link and perform a file upload mutation.

const { ApolloClient, InMemoryCache, HttpLink } = require('@apollo/client');
const { createUploadLink } = require('apollo-upload-client');

const link = createUploadLink({ uri: 'http://localhost:4000/graphql' });

const client = new ApolloClient({
  link,
  cache: new InMemoryCache()
});

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

const file = new File(['foo'], 'foo.txt', {
  type: 'text/plain',
});

client.mutate({
  mutation: UPLOAD_FILE,
  variables: { file }
}).then(response => {
  console.log(response.data.uploadFile.url);
});

Other packages similar to apollo-upload-client

apollo-link-rest

This package allows you to call REST endpoints from Apollo Client. While it does not specifically handle file uploads, it can be used to integrate RESTful file upload endpoints with Apollo Client.

graphql-request

A minimal GraphQL client that supports file uploads via the multipart request specification. It is more lightweight compared to apollo-upload-client and can be used in environments where a full Apollo Client setup is not required.

README

Enhances Apollo for intuitive file uploads via GraphQL mutations or queries. Use with Apollo upload server.

• > 2% market share browsers and React Native supported.
• MIT license.

Setup

Install with npm:

npm install apollo-upload-client

Setup Apollo client with a special network interface:

import ApolloClient from 'apollo-client'
import { createNetworkInterface } from 'apollo-upload-client'

const client = new ApolloClient({
  networkInterface: createNetworkInterface({
    uri: '/graphql'
  })
})

Alternatively enable query batching:

import ApolloClient from 'apollo-client'
import { createBatchingNetworkInterface } from 'apollo-upload-client'

const client = new ApolloClient({
  networkInterface: createBatchingNetworkInterface({
    uri: '/graphql',
    batchInterval: 10
  })
})

Also setup Apollo upload server.

Usage

Once setup, you will be able to use File and FileList objects, File arrays, and ReactNativeFile instances within query or mutation input variables.

With apollo-upload-server setup, the files upload to a temp directory. The paths and metadata will be available under the variable name in the resolver. See the server usage.

Single file

See server usage for this example.

import React from 'react'
import { graphql, gql } from 'react-apollo'

export default graphql(gql`
  mutation updateUserAvatar($userId: String!, $avatar: File!) {
    updateUserAvatar(userId: $userId, avatar: $avatar) {
      id
    }
  }
`)(({ userId, mutate }) => {
  const handleChange = ({ target }) => {
    if (target.validity.valid) {
      mutate({
        variables: {
          userId,
          avatar: target.files[0]
        }
      }).then(({ data }) => console.log('Mutation response:', data))
    }
  }

  return (
    <input
      type="file"
      accept={'image/jpeg,image/png'}
      required
      onChange={handleChange}
    />
  )
})

Multiple files

See server usage for this example.

import React from 'react'
import { graphql, gql } from 'react-apollo'

export default graphql(gql`
  mutation updateGallery($galleryId: String!, $images: [File!]!) {
    updateGallery(galleryId: $galleryId, images: $images) {
      id
    }
  }
`)(({ galleryId, mutate }) => {
  const handleChange = ({ target }) => {
    if (target.validity.valid) {
      mutate({
        variables: {
          galleryId,
          images: target.files
        }
      }).then(({ data }) => console.log('Mutation response:', data))
    }
  }

  return (
    <input
      type="file"
      accept={'image/jpeg,image/png'}
      multiple
      required
      onChange={handleChange}
    />
  )
})

React Native

React Native polyfills FormData under the hood and objects with the properties uri, type and name substitute window.File. Assuming all objects with those properties in variables are files would be risky. Use ReactNativeFile instances in query of mutation variables to mark files for upload:

import { ReactNativeFile } from 'apollo-upload-client'

// ✂

// Single file
const file = new ReactNativeFile({
  uri: uriFromCameraRoll,
  type: 'image/jpeg',
  name: 'photo.jpg'
})

// Multiple files
const files = ReactNativeFile.list({
  uri: uriFromCameraRoll1,
  type: 'image/jpeg',
  name: 'photo-1.jpg'
}, {
  uri: uriFromCameraRoll2,
  type: 'image/jpeg',
  name: 'photo-2.jpg'
})

// ✂

Inspiration

• @HriBB’s graphql-server-express-upload and apollo-upload-network-interface projects.
• @danielbuechele’s Medium article.
• @jessedvrs’s example code.

Changelog

5.0.0-alpha.1

• Updated dependencies.
• Simplified React Native setup by moving Babel config out of package.json, fixing #19 via #23.
• Export a new ReactNativeFile class to more reliably identify files for upload in React Native, via #17.
• Renamed several exports for consistency with apollo-client, via #18.
  • HTTPUploadNetworkInterface renamed UploadHTTPFetchNetworkInterface.
  • HTTPUploadBatchNetworkInterface renamed UploadHTTPBatchedNetworkInterface.
  • createBatchNetworkInterface renamed createBatchingNetworkInterface.