@uploadkitdev/core

@uploadkitdev/core

Lightweight TypeScript client for UploadKit file uploads.

Features

• Presigned URL uploads — files go directly to Cloudflare R2, never through your server
• Automatic multipart — files over 10 MB are split and uploaded in parallel
• Progress tracking — per-file progress callbacks with percentage
• Retry with backoff — configurable automatic retry on transient failures
• Abort support — cancel in-flight uploads with AbortSignal
• BYOS compatible — works with Bring Your Own Storage configuration
• Zero dependencies — ships with no runtime deps; @uploadkitdev/shared is bundled

Install

# npm
npm install @uploadkitdev/core

# pnpm
pnpm add @uploadkitdev/core

# yarn
yarn add @uploadkitdev/core

Quickstart

import { createUploadKit } from '@uploadkitdev/core';

const client = createUploadKit({ apiKey: 'uk_live_...' });

// Pick a file (browser File object)
const file = document.querySelector<HTMLInputElement>('#file')!.files![0];

const result = await client.upload({
  file,
  route: 'imageUploader', // matches your file route name
  onProgress: (pct) => console.log(`${pct}% uploaded`),
});

console.log(result.url); // https://cdn.uploadkit.dev/...

API Overview

createUploadKit(config)

Factory function that returns an UploadKitClient instance.

Option	Type	Default	Description
apiKey	string	— (required)	API key prefixed with uk_live_ or uk_test_
baseUrl	string	https://api.uploadkit.dev	Override for self-hosted or testing
maxRetries	number	3	Number of retry attempts on transient failures

client.upload(options)

Upload a single file. Returns a Promise<UploadResult>.

Option	Type	Description
file	File	Browser File object to upload
route	string	File route name defined in your handler
metadata	Record<string, unknown>	Optional metadata stored with the file
onProgress	(pct: number) => void	Progress callback (0–100)
signal	AbortSignal	Cancel the upload via AbortController

client.listFiles(options?)

List files for the project linked to your API key.

Option	Type	Description
limit	number	Max files to return (default: 20)
cursor	string	Pagination cursor from previous response

Returns Promise<{ files: UploadResult[]; nextCursor?: string }>.

client.deleteFile(key)

Permanently delete a file by its storage key. Returns Promise<void>.

Abort Uploads

const controller = new AbortController();

// Cancel after 10 seconds
setTimeout(() => controller.abort(), 10_000);

await client.upload({
  file,
  route: 'imageUploader',
  signal: controller.signal,
});

Links

• Full documentation
• React components — @uploadkitdev/react
• Next.js adapter — @uploadkitdev/next

License

MIT