Configuration

Server-side vs browser usage

@uploadkitdev/core provides two distinct factory functions depending on where your code runs:

Usage	Factory	Where it runs	Auth
Server-side (Node.js, Edge)	`createUploadKit({ apiKey })`	Route handlers, scripts, server actions	API key from `process.env.UPLOADKIT_API_KEY`
Browser	`createProxyClient({ endpoint })`	Client components, browser scripts	Calls your local endpoint — no key in browser

Never call createUploadKit({ apiKey }) in client-side code. The apiKey would be included in the browser bundle. For browser usage, use createProxyClient({ endpoint }) instead — it routes through your server which holds the key.

Server-side: createUploadKit

Use this in Node.js scripts, Route Handlers, server actions, and Edge Functions:

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

const client = createUploadKit({
  apiKey: process.env.UPLOADKIT_API_KEY!, // server env only — never NEXT_PUBLIC_
  baseUrl: 'https://api.uploadkit.dev',
  maxRetries: 3,
});

Browser: createProxyClient

Use this in client components and browser scripts. It calls your local backend endpoint, which holds the real API key:

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

const client = createProxyClient({
  endpoint: '/api/uploadkit', // your server — not the UploadKit API directly
});

createUploadKit options

Pass a UploadKitConfig object to createUploadKit(). Only apiKey is required.

Option	Type	Required	Default	Description
`apiKey`	`string`	Yes	—	Your UploadKit API key. Prefixed `uk_live_` for production or `uk_test_` for development. Get yours at dashboard.uploadkit.dev. Server-side only — never use in browser code.
`baseUrl`	`string`	No	`'https://api.uploadkit.dev'`	Override the API base URL. Useful for self-hosted UploadKit or local development proxies.
`maxRetries`	`number`	No	`3`	Number of automatic retries on transient network errors (5xx, timeouts). Set to `0` to disable retries.

Advanced example

Override all options for self-hosted or staging environments:

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

const client = createUploadKit({
  apiKey: process.env.UPLOADKIT_API_KEY!,
  // Point to a local dev server or staging environment
  baseUrl: process.env.UPLOADKIT_BASE_URL ?? 'https://api.uploadkit.dev',
  // Disable retries for tests to fail fast
  maxRetries: process.env.NODE_ENV === 'test' ? 0 : 3,
});

BYOS (Bring Your Own Storage)

If you are using BYOS mode with your own S3/R2 bucket, configure your storage credentials in the server-side @uploadkitdev/next handler instead — the core client works identically from the browser regardless of storage mode. See the BYOS guide for details.