<FileUploader />

The FileUploader component with files queued for upload

A shadcn/ui-compatible React component that uploads straight to your Openinary instance, with drag and drop, per-file progress, previews, retry, cancel and client-side validation. It installs like any other shadcn component:

pnpm dlx shadcn@latest add @openinary/file-uploader

The browser never holds your API key. It gets a short-lived presigned signature from an endpoint on your server, and uploads with that. Running Openinary Cloud? Same component, different configuration: see File Uploader on Cloud.

Security model

The component never holds an API key. Instead it uses presigned upload signatures, minted by POST /upload/sign, the same HMAC-SHA256 pattern Openinary already uses for signed delivery URLs.

Your backend requests a signature

A protected endpoint on your server calls POST /upload/sign with your Openinary API key, scoping the request to a folder and an expiry window.

The browser gets the signature

The component calls your sign() function right before uploading. It returns { signature, expires, folder }, opaque values that expire in minutes.

Openinary verifies the signature

POST /upload checks the signature against the submitted folder and expires before accepting the file. A tampered or expired signature is rejected.

Your API key never leaves your backend: only your server calls POST /upload/sign.

Prerequisites

A running Openinary instance (see Quickstart).
API_SECRET set on the instance (at least 16 characters; openssl rand -hex 32 gives you a strong 64-character one), used internally to compute the HMAC signature. Same secret used for signed delivery URLs.
An API key for your backend to call POST /upload/sign with (see API Keys).
CORS_ORIGIN set to include the origin(s) of the app embedding the uploader. Multiple origins are comma-separated:
CORS_ORIGIN=https://app.example.com,https://admin.example.com
MAX_FILE_SIZE_MB if you need to raise the default 50 MB limit.
A project already set up for shadcn/ui (components.json present). See the shadcn install guide. Requires the shadcn CLI v3 or later for namespaced registries.

Installation

Add the @openinary registry to your project’s components.json:

components.json

{
  "registries": {
    "@openinary": "https://openinary.dev/r/{name}.json"
  }
}

Add the component

pnpm dlx shadcn@latest add @openinary/file-uploader

This installs the component and its hook into components/openinary/, pulls in the shadcn button and progress dependencies, and adds NEXT_PUBLIC_OPENINARY_URL to your .env.local.

Add the signing helper

pnpm dlx shadcn@latest add @openinary/upload-token

This installs lib/upload-token.ts, a thin client for POST /upload/sign, it makes one fetch call and doesn’t compute anything cryptographic itself; Openinary does that.

Set your environment variables

.env.local

# Public, the browser calls this Openinary API directly for the upload
# /api is required in full stack mode (nginx only exposes the API under /api); drop it for API-only deployments
NEXT_PUBLIC_OPENINARY_URL=https://your-domain.com/api

# Secret, server only, an Openinary API key, never exposed to the browser
OPENINARY_API_KEY=your-openinary-api-key

Create a signing endpoint

The component needs a sign() function that returns a presigned signature. Back it with a small endpoint on your server using the helper you just installed.

Protect this endpoint with your own authentication and derive folder from the authenticated user on the server. Never trust a folder sent by the browser, or a user could upload into someone else’s scope.

Next.js (App Router)
Express
Cloudflare Workers

app/api/upload-token/route.ts

import { NextResponse } from "next/server";
import { signUpload } from "@/lib/upload-token";
// import { auth } from "@/lib/auth"; // your own auth

export async function POST() {
  // const session = await auth();
  // if (!session) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });

  const signed = await signUpload(
    process.env.NEXT_PUBLIC_OPENINARY_URL!,
    process.env.OPENINARY_API_KEY!,
    {
      expiresIn: 300,
      folder: "uploads", // e.g. `users/${session.user.id}`
    },
  );

  return NextResponse.json(signed);
}

import express from "express";
import { signUpload } from "./lib/upload-token";

const app = express();

app.post("/api/upload-token", requireAuth, async (req, res) => {
  const signed = await signUpload(
    process.env.OPENINARY_URL!,
    process.env.OPENINARY_API_KEY!,
    { expiresIn: 300, folder: `users/${req.user.id}` },
  );
  res.json(signed);
});

import { signUpload } from "./lib/upload-token";

export default {
  async fetch(request: Request, env: Env) {
    // authenticate the request first...
    const signed = await signUpload(env.OPENINARY_URL, env.OPENINARY_API_KEY, {
      expiresIn: 300,
      folder: "uploads",
    });
    return Response.json(signed);
  },
};

Keep expiresIn short. It only has to live long enough to start the upload, so 60 to 300 seconds is plenty, and the server clamps it to 3600 anyway.

Usage

Next.js
Vite / React
Restricted type/size + transformations

"use client";

import { FileUploader } from "@/components/openinary/file-uploader";

export function Uploader() {
  const sign = async () => {
    const res = await fetch("/api/upload-token", { method: "POST" });
    if (!res.ok) throw new Error("Failed to sign the upload");
    return res.json();
  };

  return (
    <FileUploader
      sign={sign}
      maxFiles={10}
      onSuccess={(files) => console.log("Uploaded:", files)}
    />
  );
}

import { FileUploader } from "@/components/openinary/file-uploader";

export function Uploader() {
  const sign = async () => {
    const res = await fetch("/api/upload-token", { method: "POST" });
    return res.json();
  };

  return (
    <FileUploader
      baseUrl={import.meta.env.VITE_OPENINARY_URL}
      sign={sign}
    />
  );
}

<FileUploader
  sign={sign} // your signing endpoint should scope folder to "uploads/avatars"
  accept={{ "image/jpeg": [".jpg", ".jpeg"], "image/png": [".png"] }}
  maxSize={5 * 1024 * 1024}     // 5 MB
  maxFiles={1}
  multiple={false}
  transformations={["w_512,h_512,c_fill,f_webp"]} // pre-warm a variant
  onSuccess={(files) => setAvatar(files[0].url)}
/>

Props

Prop	Type	Default	Description
`sign`	`() => Promise<SignedUpload> \| SignedUpload`	required	Returns `{ signature, expires, folder }` from your signing endpoint. Called before each batch and again on retry, so the signature is always fresh. The destination folder is whatever the signature is scoped to
`baseUrl`	`string`	`NEXT_PUBLIC_OPENINARY_URL`	Base URL of your Openinary API, e.g. `https://media.example.com`
`multiple`	`boolean`	`true`	Allow selecting more than one file
`disabled`	`boolean`	`false`	Block file selection and drag and drop, e.g. while a parent form submits
`accept`	`Record<string, string[]>`	Openinary media types	MIME types mapped to allowed extensions. Defaults to JPEG, PNG, WebP, AVIF, GIF, HEIC/HEIF, PSD, MP4, MOV, WebM
`maxSize`	`number`	`52428800`	Maximum file size in bytes, 50 MB. Must not exceed the server’s `MAX_FILE_SIZE_MB`
`maxFiles`	`number`		Client-side cap on file count. A UI convenience only: `POST /upload/sign` encodes no file-count limit, so it is not enforced server-side
`transformations`	`string[]`		Segments to prewarm after upload, e.g. `["w_800,f_webp"]`. See upload and prewarm
`autoUpload`	`boolean`	`false`	Upload as soon as files are added, hiding the Upload button
`className`	`string`		Extra classes on the root element
`onSuccess`	`(files: UploadedFile[]) => void`		Called with the stored files after a successful batch
`onError`	`(error: UploadFileError) => void`		Called when a file fails
`onProgress`	`(file: FileUploadState, progress: number) => void`		Called with progress from 0 to 100 per file

Styling & theming

The component is built entirely with shadcn’s design tokens (border, muted, primary, destructive, ring…), so it automatically matches your theme and dark mode. Because the source is copied into your project, you own it, edit components/openinary/file-uploader.tsx freely. Use className for one-off overrides.

Server response

onSuccess receives the files as the API stored them.

Field	Type	Description
`filename`	`string`	The stored filename
`path`	`string`	The stored path. Renamed if the name was taken, e.g. `image (1).jpg`
`url`	`string`	Root-relative delivery path, `/t/{path}`. Prefix it with your `baseUrl` for a full URL
`prewarmedUrls`	`string[]`	Image variants pre-generated from `transformations`
`queuedTransformationUrls`	`string[]`	Video variants queued for background processing

HEIC and HEIF files are converted to JPEG server-side, so the returned path may end in .jpg.

Troubleshooting

CORS error in the browser console

Add your app’s origin to CORS_ORIGIN on the Openinary instance (comma-separated for multiple origins) and restart the API. The origin must match exactly, including scheme and port.

401 'Presigned upload URL has expired'

The signature’s expires timestamp passed before the upload started. Increase expiresIn slightly (keep it under the 3600s server cap) and check for clock skew between your server and the API.

401 'Authentication required' on POST /upload

The signature didn’t verify, usually because the folder used to sign it doesn’t exactly match the folder submitted with the upload, the signature was tampered with, or the API_SECRET used by the Openinary instance changed since the signature was minted. The component always uses the folder returned by sign(), so this typically means your signing endpoint and the Openinary instance disagree, or the request was hand-crafted outside the component.

401/403 calling POST /upload/sign itself

That endpoint requires a real Openinary API key or session, check OPENINARY_API_KEY on your backend, not the browser. It should never be called directly from client code.

NEXT_PUBLIC_OPENINARY_URL is pointing at a full-stack instance’s bare domain. In full stack mode the API only lives under /api (nginx routes everything else to the web dashboard), so append /api to the URL, see the note in Set your environment variables. API-only deployments don’t need the suffix.

File rejected before upload

Client-side validation mirrors the server. Check the file type is in accept and the size is within maxSize (and the server’s MAX_FILE_SIZE_MB).

How it compares to Uploadcare

Like Uploadcare’s File Uploader, this component uses a backend-signed, short-lived credential so the browser never holds a secret. The difference: uploads go to your self-hosted Openinary instance and storage, no third-party service, no per-file pricing.

Get started

Transformations

Upload & storage

Cloud

Self-hosting

Resources

Security model

Prerequisites

Installation

Create a signing endpoint

Usage

Props

Styling & theming

Server response

Troubleshooting

How it compares to Uploadcare

​Security model

​Prerequisites

​Installation

​Create a signing endpoint

​Usage

​Props

​Styling & theming

​Server response

​Troubleshooting

​How it compares to Uploadcare

Security model

Prerequisites

Installation

Create a signing endpoint

Usage

Props

Styling & theming

Server response

Troubleshooting

How it compares to Uploadcare