Enhances Apollo GraphQL Server for intuitive file uploads via GraphQL mutations.

Usage no npm install needed!

<script type="module">
  import apollographqlApolloUploadServer from 'https://cdn.skypack.dev/@apollographql/apollo-upload-server';


Apollo upload logo


npm version Licence Github issues Github stars Travis status

Enhances Apollo for intuitive file uploads via GraphQL queries or mutations. Use with a GraphQL multipart request spec client implementation such as apollo-upload-client.


Install with peer dependencies using npm:

npm install apollo-upload-server graphql

Add the middleware just before graphql-server.


  • maxFieldSize (integer): Max allowed non-file multipart form field size in bytes; enough for your queries (default: 1 MB).
  • maxFileSize (integer): Max allowed file size in bytes (default: Infinity).
  • maxFiles (integer): Max allowed number of files (default: Infinity).


import { apolloUploadKoa } from 'apollo-upload-server'

// …

  apolloUploadKoa(/* Options */),
  graphqlKoa(/* … */)


import { apolloUploadExpress } from 'apollo-upload-server'

// …

  apolloUploadExpress(/* Options */),
  graphqlExpress(/* … */)

Custom middleware

Middleware wraps the async function processRequest which accepts a Node.js request and an optional options object as arguments. It returns a promise that resolves an operations object for a GraphQL server to consume (usually as the request body). Import it to create custom middleware:

import { processRequest } from 'apollo-upload-server'

Upload scalar

A file upload promise that resolves an object containing:

  • stream
  • filename
  • mimetype
  • encoding

It must be added to your types and resolvers:

import { makeExecutableSchema } from 'graphql-tools'
import { GraphQLUpload } from 'apollo-upload-server'

const schema = makeExecutableSchema({
  typeDefs: `scalar Upload`,
  resolvers: { Upload: GraphQLUpload }


Files uploaded via a GraphQL multipart request appear as Upload scalars in resolver arguments. The upload streams can be used to store the files in the local filesystem or in the cloud. See also apollo-upload-client usage and the example API and client.


  • Node.js v6.10+, see package.json engines.