or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdupload-http-link.mdutility-functions.md
tile.json

index.mddocs/

Apollo Upload Client

Apollo Upload Client is a terminating Apollo Link for Apollo Client that enables GraphQL file uploads through multipart requests. It automatically detects when GraphQL variables contain files (FileList, File, or Blob instances) and sends them as multipart requests following the GraphQL multipart request specification, while falling back to regular POST/GET requests for non-file operations.

Package Information

  • Package Name: apollo-upload-client
  • Package Type: npm
  • Language: JavaScript (ES modules with TypeScript support via JSDoc)
  • Installation: npm install apollo-upload-client
  • Node.js Requirements: ^20.9.0 || >=22.0.0
  • Peer Dependencies: @apollo/client@^4.0.0, graphql@14-16, rxjs@^7.3.0

Core Imports

This package uses deep imports - there is no main index module. Import specific modules directly:

ES Modules (ESM):

// Primary Apollo Link for file uploads
import UploadHttpLink from "apollo-upload-client/UploadHttpLink.mjs";

// Utility functions (optional, for customization)
import formDataAppendFile from "apollo-upload-client/formDataAppendFile.mjs";
import isExtractableFile from "apollo-upload-client/isExtractableFile.mjs";

CommonJS (for Node.js < 14 or legacy setups):

// Primary Apollo Link for file uploads
const UploadHttpLink = require("apollo-upload-client/UploadHttpLink.mjs").default;

// Utility functions (optional, for customization)
const formDataAppendFile = require("apollo-upload-client/formDataAppendFile.mjs").default;
const isExtractableFile = require("apollo-upload-client/isExtractableFile.mjs").default;

Note: This package is designed for ES modules. CommonJS usage requires Node.js configuration for ES modules or a bundler that supports mixed module types.

Basic Usage

import { ApolloClient } from "@apollo/client/core";
import { InMemoryCache } from "@apollo/client/cache";
import UploadHttpLink from "apollo-upload-client/UploadHttpLink.mjs";

// Basic setup
const client = new ApolloClient({
  cache: new InMemoryCache(),
  link: new UploadHttpLink({
    uri: "/graphql", // Optional: defaults to "/graphql"
  }),
});

// File upload in mutation variables
import { gql } from "@apollo/client/core";

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

// The file will be automatically detected and sent as multipart request
const result = await client.mutate({
  mutation: UPLOAD_FILE,
  variables: {
    file: fileFromInput, // File, Blob, or FileList instance
  },
});

Architecture

Apollo Upload Client is built around three core components:

  • UploadHttpLink: The main terminating Apollo Link that handles both file uploads and regular GraphQL requests
  • File Detection: Automatic detection of extractable files in GraphQL variables using the extract-files package
  • Multipart Requests: Implementation of the GraphQL multipart request specification for file uploads
  • Fallback Handling: Graceful fallback to regular POST/GET requests when no files are detected

The package requires Node.js 20.9+ or 22+ and modern browsers, and integrates seamlessly with Apollo Client v4+.

Capabilities

Upload HTTP Link

The core Apollo Link implementation that handles file upload detection and multipart request generation.

export default class UploadHttpLink extends ApolloLink {
  constructor(options?: UploadHttpLinkOptions);
}

interface UploadHttpLinkOptions {
  uri?: string;
  useGETForQueries?: boolean;
  isExtractableFile?: ExtractableFileMatcher;
  FormData?: typeof FormData;
  formDataAppendFile?: FormDataFileAppender;
  print?: BaseHttpLinkPrinter;
  fetch?: typeof fetch;
  fetchOptions?: RequestInit;
  credentials?: string;
  headers?: { [headerName: string]: string };
  includeExtensions?: boolean;
  includeUnusedVariables?: boolean;
}

Upload HTTP Link

Utility Functions

Helper functions for customizing file detection and FormData handling.

function formDataAppendFile(
  formData: FormData,
  fieldName: string,
  file: ExtractableFile
): void;

function isExtractableFile(value: unknown): value is ExtractableFile;

Utility Functions

Types

/**
 * Checks if a value is an extractable file.
 * @template [ExtractableFile=any] Extractable file type.
 * @callback ExtractableFileMatcher
 * @param {unknown} value Value to check.
 * @returns {value is ExtractableFile} Is the value an extractable file.
 */
type ExtractableFileMatcher<ExtractableFile = any> = (
  value: unknown
) => value is ExtractableFile;

/**
 * Appends a file extracted from the GraphQL operation to the FormData instance.
 * @template [ExtractableFile=any] Extractable file type.
 * @callback FormDataFileAppender  
 * @param {FormData} formData FormData instance to append the specified file to.
 * @param {string} fieldName Form data field name to append the file with.
 * @param {ExtractableFile} file File to append.
 */
type FormDataFileAppender<ExtractableFile = any> = (
  formData: FormData,
  fieldName: string,
  file: ExtractableFile
) => void;

/**
 * GraphQL printer function from Apollo Client.
 * @callback BaseHttpLinkPrinter
 * @param {DocumentNode} ast - GraphQL document AST to print.
 * @param {any} originalPrint - Original print function.
 * @returns {string} Printed GraphQL query string.
 */
interface BaseHttpLinkPrinter {
  (ast: DocumentNode, originalPrint: any): string;
}

// Apollo Client and GraphQL types
interface DocumentNode {
  kind: string;
  definitions: any[];
}

interface ApolloLink {
  // Base Apollo Link class from @apollo/client
}

// Extractable file types (from extract-files package)
type ExtractableFile = FileList | File | Blob;