!Apollo upload logo

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:

``sh
npm install apollo-upload-client
`

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

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

Construct ApolloClient with a terminating Apollo Link using the class UploadHttpLink. For client awareness features, compose the Apollo Link ClientAwarenessLink before the terminating link.

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.

$3

`tsx
import { gql } from "@apollo/client/core";
import { useMutation } from "@apollo/client/react";

/* React component for a uploading a file list. /
function UploadFileList() {
const [mutate] = useMutation<
{
uploadFiles: {
success: boolean;
};
},
{
files: FileList;
}
>(mutation);

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

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

$3

`tsx
import { gql } from "@apollo/client/core";
import { useMutation } from "@apollo/client/react";

/* React component for a uploading a file. /
function UploadFile() {
const [mutate] = useMutation<
{
uploadFile: {
success: boolean;
};
},
{
file: File;
}
>(mutation);

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

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

$3

`tsx
import { gql } from "@apollo/client/core";
import { useMutation } from "@apollo/client/react";

/* React component for a uploading a blob. /
function UploadBlob() {
const [mutate] = useMutation<
{
uploadFile: {
success: boolean;
};
},
{
file: Blob;
}
>(mutation);

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

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

To avoid the upload default file name blob, replace the Blob approach with File:

`ts
new File(
[value],
// Custom file name.
"text.txt",
{
type: "text/plain",
},
);
`

Requirements

- Node.js versions ^20.9.0 || >=22.0.0.
- Browsers matching the Browserslist query > 0.5%, not OperaMini all, not dead.

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:

- formDataAppendFile.mjs
- isExtractableFile.mjs
- UploadHttpLink.mjs`