Next.js App Router Setup

Install uploadworks package

Get started by installing the uploadworks package for react.

npm i uploadworks

Set Up A FileRouter

Create your first FileRoute

All files uploaded are associated with a FileRoute. The following is an example with a single FileRoute "wallpapers". Think of a FileRoute similar to an endpoint, it has:

• Permitted mime type (e.g. image/png, or wildcards like image/*)
• Maximum file size
• (Optional) middleware to authenticate and add metadata to requests
• onUploadComplete callback for when uploads are completed

import {createUploadWorks, FileRouter, UploadWorksError} from "uploadworks/server";
 
const f = createUploadWorks();
 
const auth = (req: Request) => ({ id: "fakeId" }); // Fake auth function
 
// FileRouter for your app, can contain multiple FileRoutes
export const ourFileRouter = {
    wallpapers: f({maxFileSize: 10000000, directory: "/", mime: "image/*" }) // 10mb max
        .middleware(async ({ req }) => {
            const id = await auth(req)
            return { metadata: {identifier: id}};
        })
        .onUploadComplete(async ({ file }) => {
            const id = file.metadata.id // fakeId
        })
} satisfies FileRouter;
 
export type OurFileRouter = typeof ourFileRouter;

Create a Next.js API route using the FileRouter

You'll need an API route to receive webhook requests. Your server handles all requests to upload files, alongside webhooks by our servers when files are successfully uploaded.

import {createRouteHandler} from "uploadworks/server";
import { ourFileRouter } from "./main";
 
export const { GET, POST, PUT } = createRouteHandler({
    router: ourFileRouter,
    config: {
        bucket: process.env.BUCKET!,
        key: process.env.API_KEY!,
        webhook_secret: process.env.WEBHOOK_SECRET!,
        callbackUrl: "/api/uploadworks"
    }
});

bucket: The UUID of the bucket. key: The API key either restricted to the bucket, or global. webhook_secret: The secret auth for your webhook url, used to ensure webhooks are only from UploadWorks servers. callbackUrl: The routeHandler backend Url (e.g. /api/uploadworks

Create A Component using useUploadWorks Hook

We provide a simple way to create your own upload component.

import {useUploadWorks} from "uploadworks/client";
...
 
const {startUpload, uploading} = useUploadWorks("/api/uploadworks","wallpapers",
{
    onClientUploadComplete: (slug, key, uploaded_at) => {
        alert("Success!");
    },
    onUploadError: (e) => {
        alert(e.message);
    },
    onUploadBegin: () => {},
}
)

Then in your client component, simply run startUpload(file) with the file from an input, and you're good to go!

await startUpload(file)

Final Step: Create a Webhook

Webhooks are fundemental to receiving events, such as when files are uploaded successfully.

Head over to https://upload.works/app (opens in a new tab), click on your bucket, scroll down to "Webhooks", and press NEW.

Insert your website url, along with the endpoint we setup earlier (in this example, .../api/uploadworks).

If you are testing locally, you can use a service like ngrok to reverse proxy, just make two webhook endpoints.

Make sure to copy the webhook token and place it in your code.

Nice, you're all set!

We're working on adding our own custom components, but for now you can check the example repo to learn more about implementation.

Link to Example Repository (opens in a new tab)