{"id":15512,"library":"apollo-upload-client","title":"Apollo GraphQL File Upload Link","description":"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.","status":"active","version":"19.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/jaydenseric/apollo-upload-client","tags":["javascript","graphql","multipart","request","file","upload","apollo","client","link"],"install":[{"cmd":"npm install apollo-upload-client","lang":"bash","label":"npm"},{"cmd":"yarn add apollo-upload-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add apollo-upload-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core Apollo Client library, required for creating and using Apollo Links.","package":"@apollo/client","optional":false},{"reason":"GraphQL core library, required for parsing and validating GraphQL documents.","package":"graphql","optional":false},{"reason":"Required by @apollo/client v4+ for handling observables in Apollo Link.","package":"rxjs","optional":false}],"imports":[{"note":"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.","wrong":"const createUploadLink = require('apollo-upload-client').createUploadLink;","symbol":"createUploadLink","correct":"import { createUploadLink } from 'apollo-upload-client';"},{"note":"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.","wrong":"import UploadHttpLink from 'apollo-upload-client/UploadHttpLink';","symbol":"UploadHttpLink","correct":"import { UploadHttpLink } from 'apollo-upload-client';"},{"note":"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.","symbol":"ApolloClient","correct":"import { ApolloClient, InMemoryCache } from '@apollo/client';"}],"quickstart":{"code":"import { ApolloClient, InMemoryCache, gql, ApolloProvider } from '@apollo/client';\nimport { createUploadLink } from 'apollo-upload-client';\nimport React from 'react';\nimport { useMutation } from '@apollo/client/react';\n\n// Configure the Apollo Client with the upload link\nconst uploadLink = createUploadLink({\n  uri: 'http://localhost:4000/graphql', // Replace with your GraphQL server endpoint\n});\n\nconst client = new ApolloClient({\n  cache: new InMemoryCache(),\n  link: uploadLink,\n});\n\n// GraphQL mutation definition for file upload\nconst UPLOAD_FILE_MUTATION = gql`\n  mutation uploadFile($file: Upload!) {\n    uploadFile(file: $file) {\n      filename\n      mimetype\n      encoding\n      success\n    }\n  }\n`;\n\n/** React component for uploading a single file. */\nfunction UploadFileComponent() {\n  const [uploadFile, { loading, error, data }] = useMutation(UPLOAD_FILE_MUTATION);\n\n  const handleFileChange = ({ target: { validity, files } }) => {\n    if (validity.valid && files && files[0]) {\n      uploadFile({\n        variables: {\n          file: files[0],\n        },\n      });\n    }\n  };\n\n  return (\n    <div>\n      <input type=\"file\" required onChange={handleFileChange} />\n      {loading && <p>Uploading...</p>}\n      {error && <p>Error: {error.message}</p>}\n      {data && <p>Upload successful: {data.uploadFile.filename}</p>}\n    </div>\n  );\n}\n\n// Root component to provide Apollo Client context\nfunction App() {\n  return (\n    <ApolloProvider client={client}>\n      <h1>File Upload Example</h1>\n      <UploadFileComponent />\n    </ApolloProvider>\n  );\n}\n\nexport default App;\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade Node.js to a supported version, e.g., Node.js 20.9.0 or later LTS.","message":"Node.js support has been tightened. Version 19.0.0 requires `^20.9.0 || >=22.0.0`. Older versions required different Node.js ranges.","severity":"breaking","affected_versions":">=19.0.0"},{"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`.","message":"The `@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.","severity":"breaking","affected_versions":">=18.0.0"},{"fix":"For React Native environments, alternative file handling or custom implementations for file extraction are now required. Consider external packages or manual serialization.","message":"React Native is no longer supported out of the box since v18.0.0. The `ReactNativeFile` class is no longer exported or matched by `isExtractableFile`.","severity":"breaking","affected_versions":">=18.0.0"},{"fix":"Install `rxjs@^7.3.0` alongside `apollo-upload-client` and `@apollo/client` v4.","message":"A new peer dependency `rxjs` at `^7.3.0` was added in v19.0.0, as it is a requirement for `@apollo/client` v4.","severity":"breaking","affected_versions":">=19.0.0"},{"fix":"Manually install `@apollo/client` in your project if you haven't already: `npm install @apollo/client graphql`.","message":"The 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.","severity":"breaking","affected_versions":">=15.0.0"},{"fix":"Remove any other terminating links (e.g., `HttpLink`) from your Apollo Client link chain when using `createUploadLink` or `UploadHttpLink`.","message":"This 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`.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Run `npm install @apollo/client` or `yarn add @apollo/client`.","cause":"Missing `@apollo/client` peer dependency, especially after v15.0.0.","error":"Error: Cannot find module '@apollo/client'"},{"fix":"Ensure your GraphQL server is compatible with the `graphql-multipart-request-spec` and that your resolvers are correctly processing the `Upload` scalar.","cause":"The GraphQL server does not implement the GraphQL multipart request specification, or the resolvers are not configured to handle file uploads.","error":"TypeError: Cannot read properties of undefined (reading 'files') or related file upload issues."},{"fix":"Verify that you are using `import { createUploadLink } from 'apollo-upload-client';` and that your `@apollo/client` version matches the peer dependency requirements.","cause":"Incorrect import or instantiation of `createUploadLink`, or using an incompatible version of `@apollo/client`.","error":"Error: Link is not a function or related Apollo Link initialization errors."},{"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.","cause":"Attempting to `require` an ESM-only package or incorrect module resolution setup for Node.js.","error":"SyntaxError: Named export 'createUploadLink' not found. The requested module 'apollo-upload-client' does not provide an export named 'createUploadLink'"}],"ecosystem":"npm"}