Skip to main content
This guide wires Openinary into a Next.js App Router project end to end: the registry, the two files you install, the environment, the signing route, the uploader, and how to display what came back. It works the same on Openinary Cloud and on a self-hosted instance, and the few steps that differ say which is which. Copy each file into your project as you go. Every snippet is complete.
Using Vite, Remix, or any React app whose backend isn’t Next.js? See Integrate with React.

Prerequisites

Both deployments need a project set up for shadcn/ui (components.json present) and the shadcn CLI v3 or newer, which is what resolves namespaced registries.
  • An account with a bucket, see Cloud Quickstart.
  • An API key pinned to that bucket, from Settings → API keys in the dashboard.
Nothing else. No API_SECRET, no CORS_ORIGIN allow-list, no MAX_FILE_SIZE_MB, and POST /upload accepts token-authenticated uploads from any origin.

Install

1

Register the Openinary registry

The uploader installs as source you own, not as a package. Point shadcn at the namespace once.
components.json
2

Add the component and the signing helper

The first writes components/openinary/file-uploader.tsx and its hook, 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 in this project? Don’t run shadcn init for it, that would restructure a project that never asked for it. Take use-file-upload.ts alone, verbatim, from the registry JSON, which carries each file’s target and full content. The hook holds all the logic and no styling, so you can write the markup your codebase would have written anyway.
3

Set your environment

.env.local
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. Keep it in the backend environment only, never in a NEXT_PUBLIC_* variable, never in client code, never in the repository. Confirm .env.local is gitignored.

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.
app/api/upload-token/route.ts
Two things this route has to do, and signUpload() does neither for you:
Authenticate it with whatever this app already uses. The route hands out an upload grant. If your frontend and API are separate deployments, the route belongs in the API, not in the app that renders the uploader.Derive folder server-side, from the authenticated user. A folder read from the request body is a folder any visitor can choose, including someone else’s.
Deploying to Cloudflare Workers, Deno or Bun? Add a User-Agent header to signUpload’s fetch. Those runtimes send none on outbound requests, and a request without one comes back as an HTML block page instead of JSON.
The route returns { signature, expires, folder }. Those are opaque values that expire in minutes, so they are safe to hand to the browser. Keep expiresIn short, 60 to 300 seconds is plenty; the server clamps it to 3600 anyway, and it only has to live long enough to start the upload.

Drop in the uploader

app/upload/uploader.tsx
baseUrl is optional here: the component falls back to NEXT_PUBLIC_OPENINARY_URL. sign() runs right before each upload batch and again on every retry, so an expired signature never survives a retry. The destination folder is whatever the signature is scoped to, and a folder prop on the component 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:
string
The stored path, e.g. users/42/photo.jpg. This is what you persist, not a URL. It may be de-duplicated if a file of that name already existed (photo (1).jpg), so always use this value rather than the name you sent.
string
The delivery path, with no transformation segment: /t/{path} self-hosted, /b/{bucketId}/t/{path} on Cloud. The server echoes it rather than expecting you to rebuild it, so prefix it with your base URL and use it unchanged, on either deployment.
Render it 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 the same, because it’s generated on demand: the first request for one returns 202 {"status":"processing"} rather than bytes, and an <img> can’t decode a JSON body, it fires onerror once and never retries. For a file uploaded seconds ago that first request is yours, so the picture arrives late, 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 url you stored, and you don’t need to know which deployment shape it has:
A confirmation, not a gallery. The original is full-size bytes and one CDN request, which is right for the single file that just arrived and wrong for a grid of fifty, use transformations there. Only jpg, png, webp, avif and gif decode in a browser, anything else is a link. And drop the component’s local preview once the upload finishes rather than showing both, that second copy is the same swap.

Verify

Run the app, upload a real file through the new UI, and confirm three things:
1

The signing route returns 200

With a signature, an expires and a folder in the body.
2

The path reaches its destination

The form field, state, or column where this project keeps such a value.
3

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

NEXT_PUBLIC_OPENINARY_URL has the wrong shape for your deployment. A full-stack self-hosted instance needs the /api suffix, because nginx routes everything else to the dashboard. Cloud and API-only deployments must not have it.
The API key is missing, disabled, expired, or the call is coming from the browser, where the key shouldn’t be at all. Check OPENINARY_API_KEY on your backend.
The signature’s expires passed before the upload started, or the folder used to sign doesn’t match the one submitted. The component always uses the folder sign() returned and re-signs on retry, so this normally means the signing route and the instance disagree. On self-hosted, also check for clock skew and for an API_SECRET that changed after the signature was minted.
Self-hosted: add your app’s origin to CORS_ORIGIN and restart the API, matching scheme and port exactly. Cloud: POST /upload accepts token-authenticated uploads from any origin, so a CORS failure there is usually a browser calling /upload/sign or /storage directly. Those are backend-only.
An upload that would push the account past its storage allowance is refused with 402 and a body naming the feature. Surface it, don’t retry it, the retry fails identically until the plan or the usage changes. See Plans and limits.
You’re rendering a transformation of a file that was just uploaded, so your own request is the one generating it. Show the original instead, see Render it once, as the original.

Next steps

Component reference

Every prop, styling, and the full server response shape.

Transformations

Resizing, cropping, format conversion, video, and signed delivery URLs.