Dropbox

Dropbox via the official SDK. Path-addressable, virtual keys map directly to Dropbox paths - no cache.

Installation

dropbox is an optional peer dependency of files-sdk - install alongside the SDK so the adapter’s imports resolve at runtime.

npm install files-sdk dropbox

pnpm add files-sdk dropbox

yarn add files-sdk dropbox

bun add files-sdk dropbox

Dropbox via the official dropbox SDK. Path-addressable like OneDrive (/folder/file.txt), so virtual keys map directly to Dropbox paths - no virtual-key cache, no bookkeeping. Four auth shapes (pre-built client, static or dynamic access token, OAuth refresh token + app key, or env-var fallback) cover personal Dropbox, Dropbox Business, and team-space deployments.

import { Files } from "files-sdk";
import { dropbox } from "files-sdk/dropbox";

// OAuth2 refresh-token flow (recommended for server-side apps).
// The adapter exchanges the refresh token at api.dropboxapi.com/oauth2/token
// and caches the access token until ~60s before expiry.
const files = new Files({
  adapter: dropbox({
    refreshToken: process.env.DROPBOX_REFRESH_TOKEN!,
    appKey: process.env.DROPBOX_APP_KEY!,
    appSecret: process.env.DROPBOX_APP_SECRET, // omit for PKCE public clients
    rootFolderPath: "/Uploads",
    // publicByDefault: true → upload() also creates a public shared link
    //                       and url() returns it (rewritten to ?dl=1 for
    //                       direct download).
  }),
});

Options

PropType

rootFolderPath?string

Logical "bucket root" — virtual keys live under this folder path on the Dropbox account. Must already exist; the adapter does not create folders. Path is normalized: leading slash is added, trailing slashes stripped. Defaults to the account root.

Typestring

publicByDefault?boolean

When `true`, `upload()` also creates a public shared link (anyone with the link can view) and `url()` returns that link's `url` (rewritten to `?dl=1` for direct download). When `false` (default), `url()` mints a 4-hour temporary link via `filesGetTemporaryLink`. **Plan policy note:** public shared links may be restricted on Dropbox Business teams; the adapter surfaces Dropbox's `access_denied` error unmodified in that case.

Typeboolean

publicBaseUrl?string

Origin used to build URLs from `url()`. When set, `url(key)` returns `${publicBaseUrl}/${key}` and skips both signing and shared-link creation. Useful when a CDN sits in front of pre-shared Dropbox links.

Typestring

defaultUrlExpiresIn?number

Default expiry, in seconds, for the temporary download links returned by `url()` when neither `publicByDefault` nor `publicBaseUrl` is set. **Validated only**: `filesGetTemporaryLink` takes no expiry parameter, so every link actually lives ~4 hours (14400s, the Dropbox fixed lifetime) regardless of what's requested — values above 14400 throw, values below are accepted but the link still outlives them. Don't rely on a short `expiresIn` as a security control with this adapter. Defaults to 3600.

Typenumber

client?Dropbox

Pre-built `Dropbox` client — escape hatch for callers that already wire auth themselves (e.g. with team-space `pathRoot`, custom headers, or shared `DropboxAuth`).

TypeDropbox

accessToken?string | (() => string | Promise<string>)

Static or dynamic access token. Pass a string for a one-shot token, or a function returning a fresh token on each call. The adapter does not cache the result of a callable — your callable is responsible for caching/refresh.

Typestring | (() => string | Promise<string>)

refreshToken?string

OAuth2 refresh-token flow. Tokens are exchanged at `https://api.dropboxapi.com/oauth2/token` and cached until ~60s before expiry. `appSecret` is required for confidential clients (server-side apps); PKCE-only public clients should pass `appKey` alone.

Typestring

appKey?string

Dropbox app key (client_id). Required when `refreshToken` is set.

Typestring

appSecret?string

Dropbox app secret (client_secret). Required for confidential clients.

Typestring

Compatibility

Method	Status	Notes
`upload`	⚠️	Single-call `filesUpload` up to Dropbox’s 150 MB limit; bodies above that automatically switch to `filesUploadSession*` (chunked, up to 350 GB) buffered into memory. Stream bodies are buffered up-front since the SDK has no streaming form. User `metadata` and `cacheControl` throw - Dropbox has no native arbitrary-metadata field; use `raw` with `property_groups` (registered template required) if you need it.
`download`	⚠️	`filesDownload` buffers the full body - the SDK has no streaming download primitive. For `as: 'stream'`, the adapter mints a temporary link and fetches it via standard HTTP, which exposes a `ReadableStream` body.
`delete`	✅
`list`	⚠️	Recursive listing under `rootFolderPath` via `filesListFolder({ recursive: true })`; folder entries are filtered out. `prefix` is matched client-side within the returned page and can under-return when the prefix isn’t satisfied within a single page. Pagination uses Dropbox’s opaque cursor via `filesListFolderContinue`.
`search`	⚠️	Built on `listAll` — inherits this adapter’s `list` behavior above. Client-side key match (glob, regex, substring, exact).
`head`	⚠️	Dropbox doesn’t store user-supplied content types - `filesUpload` accepts no Content-Type. `head()` returns a type inferred from the filename extension (or `application/octet-stream` when unknown). `etag` is Dropbox’s `rev` field.
`exists`	⚠️	Resolves via `filesGetMetadata` and returns `false` for folder or deleted entries at the path - matches Dropbox’s semantics where the same path can hold a folder or a tombstone. Only true file entries return `true`.
`copy`	✅
`url`	⚠️	Default mints a 4-hour temporary link via `filesGetTemporaryLink` - the API takes no expiry parameter, so `expiresIn` is validated only: values above Dropbox’s 14400s (4h) fixed lifetime throw, values below are accepted but the link still lives ~4h. Don’t rely on a short `expiresIn` as a security control here. With `publicByDefault: true`, `upload()` creates a public shared link and `url()` returns it (rewritten to `?dl=1` for direct download). With `publicBaseUrl`, returns `<publicBaseUrl>/<key>`. `responseContentDisposition` always throws - Dropbox links have no Content-Disposition override.
`signedUploadUrl`	❌	Throws - Dropbox’s `filesGetTemporaryUploadLink` returns a URL that expects POST with a raw body, which fits neither the SDK’s PUT-with-headers nor POST-with-form-fields shape. Use `upload()` or drop to `raw.filesGetTemporaryUploadLink(...)` for client-side uploads.

Dropbox

Installation

Usage

Options

Compatibility