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

apollo-upload-client

A terminating Apollo Link for Apollo Client that fetches a GraphQL multipart request if the GraphQL variables contain files (by default FileList, File, or Blob instances), or else fetches a regular GraphQL POST or GET request (depending on the config and GraphQL operation).

• Installation
• Examples
• Requirements
• Exports

Installation

To install with npm, run:

npm install apollo-upload-client

Polyfill any required globals (see Requirements) that are missing in your server and client environments.

Remove any uri, credentials, or headers options from the ApolloClient constructor.

Apollo Client can only have 1 terminating Apollo Link that sends the GraphQL requests; if one such as HttpLink is already setup, remove it.

Initialize the client with a terminating Apollo Link using the function createUploadLink.

Also ensure the GraphQL server implements the GraphQL multipart request spec and that uploads are handled correctly in resolvers.

Examples

Use FileList, File, or Blob instances anywhere within query or mutation variables to send a GraphQL multipart request.

See also the example API and client.

FileList

import { gql, useMutation } from "@apollo/client";

const MUTATION = gql`
  mutation ($files: [Upload!]!) {
    uploadFiles(files: $files) {
      success
    }
  }
`;

function UploadFiles() {
  const [mutate] = useMutation(MUTATION);

  return (
    <input
      type="file"
      multiple
      required
      onChange={({ target: { validity, files } }) => {
        if (validity.valid)
          mutate({
            variables: {
              files,
            },
          });
      }}
    />
  );
}

File

import { gql, useMutation } from "@apollo/client";

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

function UploadFile() {
  const [mutate] = useMutation(MUTATION);

  return (
    <input
      type="file"
      required
      onChange={({
        target: {
          validity,
          files: [file],
        },
      }) => {
        if (validity.valid)
          mutate({
            variables: {
              file,
            },
          });
      }}
    />
  );
}

Blob

import { gql, useMutation } from "@apollo/client";

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

function UploadFile() {
  const [mutate] = useMutation(MUTATION);

  return (
    <input
      type="text"
      required
      onChange={({ target: { validity, value } }) => {
        if (validity.valid) {
          const file = new Blob([value], { type: "text/plain" });

          // Optional, defaults to `blob`.
          file.name = "text.txt";

          mutate({
            variables: {
              file,
            },
          });
        }
      }}
    />
  );
}

Requirements

• Node.js versions ^18.15.0 || >=20.4.0.
• Browsers matching the Browserslist query > 0.5%, not OperaMini all, not dead.

Consider polyfilling:

• AbortController
• fetch
• FormData

Projects must configure TypeScript to use types from the ECMAScript modules that have a // @ts-check comment:

• compilerOptions.allowJs should be true.
• compilerOptions.maxNodeModuleJsDepth should be reasonably large, e.g. 10.
• compilerOptions.module should be "node16" or "nodenext".

Exports

The npm package apollo-upload-client features optimal JavaScript module design. It doesn’t have a main index module, so use deep imports from the ECMAScript modules that are exported via the package.json field exports:

• createUploadLink.mjs
• formDataAppendFile.mjs
• isExtractableFile.mjs

Changelog

18.0.0

Major

• Updated Node.js support to ^18.15.0 || >=20.4.0.

• Updated the @apollo/client peer dependency to ^3.8.0.

• Updated the extract-files dependency to v13.

  • React Native is no longer supported out of the box.

    The class ReactNativeFile is no longer exported, or matched by the function isExtractableFile.

    This class was bloating non React Native environments with an extra module, increasing bundle sizes when building and adding an extra step to ESM loading waterfalls in browsers.

    It’s the responsibility of Facebook to adhere to web standards and implement spec-complaint Blob, File, and FormData globals in the React Native environment.

    To migrate, React Native projects that are unable to use the standard globals can manually implement a class ReactNativeFile and match it with a custom function isReactNativeFile for use with the function createUploadLink option isExtractableFile.

  • “Plain” objects in the GraphQL operation that aren’t Object instances (e.g. Object.create(null)) are now also deep cloned when searching for extractable files.

• Updated dev dependencies, some of which require newer Node.js versions than previously supported.

• Use the Node.js test runner API and remove the dev dependency test-director.

• Refactored tests to use the standard AbortController, AbortSignal, File, FormData, and Response APIs available in modern Node.js and removed the dev dependencies abort-controller, formdata-node, and node-fetch.

• Public modules are now individually listed in the package files and exports fields.

• Removed the package main index module; deep imports must be used. To migrate:

  - import {
  -   createUploadLink,
  -   formDataAppendFile,
  -   isExtractableFile
  - } from "apollo-upload-client";
  + import createUploadLink from "apollo-upload-client/createUploadLink.mjs";
  + import formDataAppendFile from "apollo-upload-client/formDataAppendFile.mjs";
  + import isExtractableFile from "apollo-upload-client/isExtractableFile.mjs";
  

• Shortened public module deep import paths, removing the /public/. To migrate:

  - import createUploadLink from "apollo-upload-client/public/createUploadLink.js";
  + import createUploadLink from "apollo-upload-client/createUploadLink.mjs";
  
  - import formDataAppendFile from "apollo-upload-client/public/formDataAppendFile.js";
  + import formDataAppendFile from "apollo-upload-client/formDataAppendFile.mjs";
  
  - import isExtractableFile from "apollo-upload-client/public/isExtractableFile.js";
  + import isExtractableFile from "apollo-upload-client/isExtractableFile.mjs";
  

• The API is now ESM in .mjs files instead of CJS in .js files, accessible via import but not require.

• Implemented TypeScript types via JSDoc comments.

  Types published in @types/apollo-upload-client should no longer be used.

  Projects must configure TypeScript to use types from the ECMAScript modules that have a // @ts-check comment:

  • compilerOptions.allowJs should be true.
  • compilerOptions.maxNodeModuleJsDepth should be reasonably large, e.g. 10.
  • compilerOptions.module should be "node16" or "nodenext".

• Internally, use the function selectHttpOptionsAndBodyInternal that was added in @apollo/client v3.5.5.

Minor

• Added a new option print for the function createUploadLink, to customize how the GraphQL query or mutation AST prints to a string for transport. It that works like the same option for HttpLink.

Patch

• Updated dev dependencies.
• Simplified dev dependencies and config for ESLint.
• Integrated the ESLint plugin eslint-plugin-optimal-modules.
• Check TypeScript types via a new package types script.
• Removed the jsdoc-md dev dependency and the related package scripts, replacing the readme “API” section with a manually written “Exports” section.
• Updated the package.json field repository to conform to new npm requirements.
• Updated GitHub Actions CI config:
  • The workflow still triggers on push, but no longer on pull request.
  • The workflow can now be manually triggered.
  • Run tests with Node.js v18, v20, v21.
  • Updated actions/checkout to v4.
  • Updated actions/setup-node to v3.
• Use the node: URL scheme for Node.js builtin module imports.
• Reorganized the test file structure.
• In tests, for objects with the property headers that as of @apollo/client v3.7.0 is a null-prototype object, use the assertion deepEqual instead of deepStrictEqual.
• Tweaked code for type safety.
• Updated documentation, including link URLs.
• Refactored example code in the readme.
• Removed the readme badges.