<FileUploader /> in your React app, a route on your own API that mints a short-lived upload signature, and an API key that never reaches the bundle. Two shadcn commands install both pieces as source you own. This is the setup for a Vite frontend with a separate Express, Hono or Fastify API behind it. The flow is identical on Openinary Cloud and on a self-hosted instance, and the steps that differ say which is which.
On Next.js the route handler and the uploader live in one project, which changes where the environment variables go. See Integrate with Next.js.
Install
Register the Openinary registry
components.json present) and the shadcn CLI v3 or newer, which resolves namespaced registries.Add the component and the signing helper
components/openinary/file-uploader.tsx and its hook into the frontend, with drag & drop, per-file progress, previews, retry, cancel and client-side validation. The second writes lib/upload-token.ts, a thin client for POST /upload/sign.No shadcn here? Don’t run shadcn init, it restructures a project that never asked for it. Take use-file-upload.ts verbatim from the registry JSON, which carries each file’s target and content. The hook is all logic and no styling, so write your own markup.Set your environment
YOUR_OPENINARY_URL is https://cdn.openinary.dev on Cloud. Self-hosted, it’s your own domain, plus /api in full stack mode where nginx reserves the root for the dashboard.The API key mints upload signatures, so it is a secret. Vite inlines every VITE_* variable into the bundle, so keep the key out of VITE_*, out of client code, and out of the repository.What each deployment needs
- Cloud
- Self-hosted
- An account with a bucket, see Cloud Quickstart.
- An API key pinned to that bucket, from Settings → API keys in the dashboard.
API_SECRET, no CORS_ORIGIN allow-list, no MAX_FILE_SIZE_MB, and POST /upload accepts token-authenticated uploads from any origin.Mint the signature on your server
Your backend holds the key and hands the browser a signature that dies in five minutes.signUpload() makes that call. You write the route around it, in whatever framework your API uses.
app.example.com calling an API on api.example.com needs CORS on your own signing route, separate from anything Openinary is configured with.
signUpload sends its own User-Agent, so Cloudflare Workers, Deno and Bun work without extra setup. Pass a userAgent option if you want to identify your app specifically.
The route returns { signature, expires, folder }, opaque values that expire in minutes and are safe to hand to the browser. Keep expiresIn short, 60 to 300 seconds is plenty. The server clamps it to 3600 anyway.
Drop in the uploader
baseUrl is required outside Next.js: the component’s fallback reads process.env.NEXT_PUBLIC_OPENINARY_URL, which doesn’t exist here.
sign() runs before each upload batch and again on every retry, so an expired signature never survives a retry. The folder is whatever the signature is scoped to, and a folder prop is ignored when a signature is used.
The transformations prop pre-warms variants at upload time on a self-hosted instance, see Upload & Pre-warm. On Cloud it is ignored, along with the prewarmedUrls and queuedTransformationUrls fields, because variants are generated on the first request instead.
For the full props table and styling, see <FileUploader />. On Cloud, the Cloud page adds the behaviour table for the props that differ.
Render it once, as the original
onSuccess gives you two values worth knowing apart.
url once and never swap it for another URL. That form is served straight from storage, so it decodes on the first try, every time.
A sized transformation can’t promise that, because it’s generated on demand. On Openinary Cloud the first request for one returns 202 {"status":"processing"} rather than bytes. Self-hosted, that applies to video, while images are processed inline and come back as bytes on the first request. Where the 202 happens, an <img> can’t decode a JSON body: it fires onerror once and never retries. For a file uploaded seconds ago that request is yours, so the picture arrives after a broken-image frame.
Transformed URLs are for the next page load, once the file is at rest. Insert the transformation right after /t/ in the stored url, whatever the deployment shape:
Verify
Run the app, upload a real file through the new UI, and confirm three things.The signing route returns 200
signature, an expires and a folder in the body.The path reaches its destination
The image decodes on the first try
naturalWidth > 0, no retry, no flicker. If you needed a retry to see it, you’re rendering a transformation rather than the original.Common failures
signUpload throws 'Failed to sign upload (HTTP 404)', or the response redirects to /login
signUpload throws 'Failed to sign upload (HTTP 404)', or the response redirects to /login
OPENINARY_URL has the wrong shape for your deployment. A full-stack self-hosted instance needs the /api suffix. Cloud and API-only deployments must not have it.401 on POST /upload/sign
401 on POST /upload/sign
OPENINARY_API_KEY on your backend.401 on POST /upload after signing
401 on POST /upload after signing
expires passed before the upload started, or the folder used to sign doesn’t match the one submitted. The component re-signs on retry, so this usually means the signing route and the instance disagree. Self-hosted, also check clock skew and an API_SECRET that changed after the signature was minted.CORS error in the console
CORS error in the console
POST /upload self-hosted, add the app’s origin to CORS_ORIGIN and restart the API, matching scheme and port exactly. Cloud accepts token-authenticated uploads from any origin, so a failure there is usually a browser calling /upload/sign or /storage directly. Those are backend-only.402 quota_exceeded (Cloud only)
402 quota_exceeded (Cloud only)
402 and a body naming the feature. Surface it, don’t retry, the retry fails identically until the plan or the usage changes. See Plans and limits.The image appears late, or flashes broken first
The image appears late, or flashes broken first