Registry / http-networking / apollo-upload-client

apollo-upload-client

JSON →
library19.0.0jsnpmunverified

apollo-upload-client is a terminating Apollo Link for Apollo Client that facilitates file uploads within GraphQL mutations using the GraphQL multipart request specification. It automatically detects `FileList`, `File`, or `Blob` instances in GraphQL variables and constructs a multipart request, falling back to a standard GraphQL POST or GET request otherwise. The current stable version is 19.0.0, with major versions released somewhat frequently to align with `@apollo/client` updates and Node.js LTS changes. Its primary differentiator is seamless integration with Apollo Client for file uploads, abstracting the multipart request complexity, and adhering to the community-standard GraphQL multipart request specification. It requires a compatible server-side implementation that also follows the specification.

npm install apollo-upload-client
INSTALL
IMPORT
SIG · APOLLO-UPLOAD-CLIE
A
apollo-upload-client
http-networkingjavascriptv19.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createUploadLink
import { createUploadLink } from 'apollo-upload-client';
const createUploadLink = require('apollo-upload-client').createUploadLink;
The library is ESM-first. While CJS might work via transpilation, direct require is not recommended. `createUploadLink` is the primary factory function for the link.
UploadHttpLink
import { UploadHttpLink } from 'apollo-upload-client';
import UploadHttpLink from 'apollo-upload-client/UploadHttpLink';
Since v16, deep imports are generally discouraged, and the main export `UploadHttpLink` class is preferred over direct file path imports. `createUploadLink` is a function that returns an instance of this class.
ApolloClient
import { ApolloClient, InMemoryCache } from '@apollo/client';
This is a peer dependency; `apollo-upload-client` integrates with it, but does not export it directly. It is shown here as it's fundamental to using the upload link.

This quickstart demonstrates how to set up `apollo-upload-client` with Apollo Client, define a GraphQL mutation for file uploads, and use it within a React component. It initializes `createUploadLink` with a GraphQL endpoint and wraps a file input with a `useMutation` hook to send the selected file to the server.

import { ApolloClient, InMemoryCache, gql, ApolloProvider } from '@apollo/client'; import { createUploadLink } from 'apollo-upload-client'; import React from 'react'; import { useMutation } from '@apollo/client/react'; // Configure the Apollo Client with the upload link const uploadLink = createUploadLink({ uri: 'http://localhost:4000/graphql', // Replace with your GraphQL server endpoint }); const client = new ApolloClient({ cache: new InMemoryCache(), link: uploadLink, }); // GraphQL mutation definition for file upload const UPLOAD_FILE_MUTATION = gql` mutation uploadFile($file: Upload!) { uploadFile(file: $file) { filename mimetype encoding success } } `; /** React component for uploading a single file. */ function UploadFileComponent() { const [uploadFile, { loading, error, data }] = useMutation(UPLOAD_FILE_MUTATION); const handleFileChange = ({ target: { validity, files } }) => { if (validity.valid && files && files[0]) { uploadFile({ variables: { file: files[0], }, }); } }; return ( <div> <input type="file" required onChange={handleFileChange} /> {loading && <p>Uploading...</p>} {error && <p>Error: {error.message}</p>} {data && <p>Upload successful: {data.uploadFile.filename}</p>} </div> ); } // Root component to provide Apollo Client context function App() { return ( <ApolloProvider client={client}> <h1>File Upload Example</h1> <UploadFileComponent /> </ApolloProvider> ); } export default App;
Debug
Known issues
breakingNode.js support has been tightened. Version 19.0.0 requires `^20.9.0 || >=22.0.0`. Older versions required different Node.js ranges.
fix
Upgrade Node.js to a supported version, e.g., Node.js 20.9.0 or later LTS.
affects: >=19.0.0
breakingThe `@apollo/client` peer dependency was updated to `^4.0.0` in v19.0.0 and `^3.8.0` in v18.0.0. Mismatching versions can lead to runtime errors or unexpected behavior.
fix
Ensure your `@apollo/client` package aligns with the `apollo-upload-client` peer dependency range. For v19.0.0, install `@apollo/client@^4.0.0`.
affects: >=18.0.0
breakingReact Native is no longer supported out of the box since v18.0.0. The `ReactNativeFile` class is no longer exported or matched by `isExtractableFile`.
fix
For React Native environments, alternative file handling or custom implementations for file extraction are now required. Consider external packages or manual serialization.
affects: >=18.0.0
breakingA new peer dependency `rxjs` at `^7.3.0` was added in v19.0.0, as it is a requirement for `@apollo/client` v4.
fix
Install `rxjs@^7.3.0` alongside `apollo-upload-client` and `@apollo/client` v4.
affects: >=19.0.0
breakingThe package moved from `@apollo/client` as a direct dependency to a peer dependency in v15.0.0. This change requires developers to explicitly install `@apollo/client` themselves.
fix
Manually install `@apollo/client` in your project if you haven't already: `npm install @apollo/client graphql`.
affects: >=15.0.0
gotchaThis library is a 'terminating link'. Apollo Client can only have one terminating link. If you're already using `HttpLink`, you must replace it with `createUploadLink`.
fix
Remove any other terminating links (e.g., `HttpLink`) from your Apollo Client link chain when using `createUploadLink` or `UploadHttpLink`.
affects: all
Errors
Common errors & fixes
Error: Cannot find module '@apollo/client'
Missing `@apollo/client` peer dependency, especially after v15.0.0.
fix
Run `npm install @apollo/client` or `yarn add @apollo/client`.
TypeError: Cannot read properties of undefined (reading 'files') or related file upload issues.
The GraphQL server does not implement the GraphQL multipart request specification, or the resolvers are not configured to handle file uploads.
fix
Ensure your GraphQL server is compatible with the `graphql-multipart-request-spec` and that your resolvers are correctly processing the `Upload` scalar.
Error: Link is not a function or related Apollo Link initialization errors.
Incorrect import or instantiation of `createUploadLink`, or using an incompatible version of `@apollo/client`.
fix
Verify that you are using `import { createUploadLink } from 'apollo-upload-client';` and that your `@apollo/client` version matches the peer dependency requirements.
SyntaxError: Named export 'createUploadLink' not found. The requested module 'apollo-upload-client' does not provide an export named 'createUploadLink'
Attempting to `require` an ESM-only package or incorrect module resolution setup for Node.js.
fix
Ensure your project uses ES modules (`import`/`export`) or is transpiled correctly. For Node.js, confirm `type: module` in `package.json` or use `.mjs` files.
Upgrade
Version history
19.0.0latest on npm
Audit
Dependencies
@apollo/clientrequiredCore Apollo Client library, required for creating and using Apollo Links.
graphqlrequiredGraphQL core library, required for parsing and validating GraphQL documents.
rxjsrequiredRequired by @apollo/client v4+ for handling observables in Apollo Link.
Agent activity
15 hits · last 30 days
node
14
OpenAI (training)
1
Resources