A terminating Apollo Link for Apollo Client that handles GraphQL file uploads using multipart requests.
npm install @hyperse/apollo-upload-clientA terminating Apollo Link for Apollo Client that handles GraphQL file uploads using multipart requests. When GraphQL variables contain files (FileList, File, or Blob instances), it sends a multipart/form-data request. Otherwise, it falls back to standard GraphQL POST/GET requests based on the configuration and operation type.




- 🚀 Seamless Integration: Drop-in replacement for Apollo Client's HttpLink
- 📁 File Upload Support: Handles File, Blob, and FileList instances automatically
- 🔄 Smart Request Handling: Automatically switches between multipart and regular GraphQL requests
- 🎯 TypeScript Support: Full TypeScript support with comprehensive type definitions
- 🌐 Universal Compatibility: Works in browsers, React Native, and Node.js environments
- ⚡ Performance Optimized: Efficient file extraction and request handling
``bash`
npm install @hyperse/apollo-upload-clientor
yarn add @hyperse/apollo-upload-clientor
pnpm add @hyperse/apollo-upload-client
`typescript
import { ApolloClient, InMemoryCache, ApolloLink } from '@apollo/client';
import { UploadHttpLink } from '@hyperse/apollo-upload-client';
const client = new ApolloClient({
cache: new InMemoryCache(),
link: ApolloLink.from([
new UploadHttpLink({
uri: '/graphql',
}),
]),
});
`
`typescript
import { ApolloClient, InMemoryCache, ApolloLink } from '@apollo/client';
import { UploadHttpLink } from '@hyperse/apollo-upload-client';
const client = new ApolloClient({
cache: new InMemoryCache(),
link: ApolloLink.from([
new ClientAwarenessLink(),
// Add other links here (e.g., error handling, authentication)
new UploadHttpLink({
uri: '/graphql',
}),
]),
});
`
`typescript
import { gql, useMutation } from '@apollo/client';
const UPLOAD_FILE = gql
mutation UploadFile($file: Upload!, $description: String) {
uploadFile(file: $file, description: $description) {
id
filename
url
}
};
function FileUploadComponent() {
const [uploadFile, { loading, error, data }] = useMutation(UPLOAD_FILE);
const handleFileChange = (event) => {
const file = event.target.files[0];
if (file) {
uploadFile({
variables: {
file: file,
description: 'My uploaded file'
}
});
}
};
return (
Uploading...
}Error: {error.message}
}File uploaded: {data.uploadFile.filename}
}$3
`typescript
const UPLOAD_MULTIPLE_FILES = gql;function MultipleFileUploadComponent() {
const [uploadFiles, { loading }] = useMutation(UPLOAD_MULTIPLE_FILES);
const handleFilesChange = (event) => {
const files = Array.from(event.target.files);
if (files.length > 0) {
uploadFiles({
variables: {
files: files
}
});
}
};
return (
);
}
`API Reference
$3
The main class that handles file uploads in GraphQL requests.
#### Constructor Options
`typescript
interface UploadHttpLinkOptions {
// HTTP Link options
uri?: string;
fetch?: WindowOrWorkerGlobalScope['fetch'];
headers?: Record;
credentials?: RequestCredentials; // Upload-specific options
FormData?: typeof FormData;
isExtractableFile?: ExtractableFileMatcher;
formDataAppendFile?: FormDataFileAppender;
}
`#### Options
-
uri (string, default: /graphql): The GraphQL endpoint URI
- fetch (function): Custom fetch implementation
- headers (object): Additional HTTP headers
- credentials (string): Request credentials policy
- FormData (class): Custom FormData implementation
- isExtractableFile (function): Custom file detection logic
- formDataAppendFile (function): Custom file appending logic$3
`typescript
type ExtractableFile = File | Blob;
`Supported file types that can be automatically detected and uploaded.
$3
Utility function to extract files from objects and create upload-ready data.
`typescript
import {
extractFiles,
isExtractableFile,
} from '@hyperse/apollo-upload-client/extractFiles';const { clone, files } = extractFiles(
{ file: myFile, data: { nested: { file: anotherFile } } },
isExtractableFile
);
``1. Request Analysis: The link analyzes GraphQL operation variables for file objects
2. Smart Routing:
- If files are detected: Creates a multipart/form-data request
- If no files: Falls back to regular GraphQL HTTP request
3. File Extraction: Extracts files and their object paths from variables
4. Request Construction: Builds the multipart request according to the GraphQL multipart request specification
5. Response Handling: Processes the response and forwards it to Apollo Client
MIT License - see LICENSE file for details.
- 📖 Documentation
- 🐛 Issue Tracker
- 💬 Discussions
- Apollo Client - GraphQL client for React
- GraphQL Multipart Request Spec - File upload specification
---
Made with ❤️ by the Hyperse team