@hyperse/apollo-upload-client

A 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.


Features

- 🚀 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

Installation

``bash
npm install @hyperse/apollo-upload-client


or

yarn add @hyperse/apollo-upload-client

or

pnpm add @hyperse/apollo-upload-client
`

Quick Start

$3

`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',
}),
]),
});
`

$3

`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',
}),
]),
});
`

Usage

$3

`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 (



);
}
`

$3

`typescript
const UPLOAD_MULTIPLE_FILES = gql
mutation UploadMultipleFiles($files: [Upload!]!) {
uploadMultipleFiles(files: $files) {
id
filename
url
}
}
;

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
);
``

How It Works

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

License

MIT License - see LICENSE file for details.

Support

- 📖 Documentation
- 🐛 Issue Tracker
- 💬 Discussions

Related Projects

- Apollo Client - GraphQL client for React
- GraphQL Multipart Request Spec - File upload specification

---

Made with ❤️ by the Hyperse team