@stack-upload-orchestrator/next

Next.js App Router upload handlers built on @stack-upload-orchestrator/node.

Installation

npm install @stack-upload-orchestrator/next @stack-upload-orchestrator/node

Requires Next.js ≥ 13 (App Router).

createUploadHandler

Creates a Next.js App Router POST route handler for standard multipart uploads.

// app/api/upload/route.ts
import { createUploadHandler } from '@stack-upload-orchestrator/next';
import { LocalStorage } from '@stack-upload-orchestrator/storage-local';

export const POST = createUploadHandler({
  storage: new LocalStorage({ destination: './public/uploads' }),
  validation: {
    allowedTypes: ['image/*', 'application/pdf'],
    maxFileSize: '10MB',
    maxFiles: 5,
  },
});

On success, responds with { files: UploadResult[] }. On error, responds with { error: string } and status 400.

Options (UploadHandlerOptions)

| Option | Type | Description | |---|---|---| | storage | NodeStorageAdapter | Where to persist uploaded files | | validation | ValidationOptions | Size, type, extension, and count rules | | onBeforeUpload | (meta) => Promise<void> | Hook before each file is stored. Throw to reject. | | onUploadComplete | (result, meta) => Promise<void> | Hook after each file is stored. | | onError | (error, meta) => void | Called when an individual file fails. |

createChunkUploadHandler

Creates a route handler for chunked uploads — use this for large files.

// app/api/upload/chunk/route.ts
import { createChunkUploadHandler } from '@stack-upload-orchestrator/next';
import { MemoryChunkStore } from '@stack-upload-orchestrator/node';
import { S3Storage } from '@stack-upload-orchestrator/storage-s3';
import { S3Client } from '@aws-sdk/client-s3';

const store = new MemoryChunkStore();
const storage = new S3Storage({
  client: new S3Client({ region: 'us-east-1' }),
  bucket: 'my-bucket',
});

export const POST = createChunkUploadHandler({ store, storage });

The client must send each chunk as a multipart/form-data POST with these fields:

| Field | Description | |---|---| | x-chunk-index | Zero-based index of this chunk | | x-chunk-total | Total number of chunks | | x-file-name | Original filename | | x-file-size | Total file size in bytes | | x-upload-id | Unique ID for the upload session |

When the last chunk arrives the handler assembles the file, stores it, and responds with { done: true, file: UploadResult }. Intermediate chunks respond with { done: false }.

Using with @stack-upload-orchestrator/react

// components/Uploader.tsx
import { useUploadium, UploadDropzone } from '@stack-upload-orchestrator/react';

export function Uploader() {
  return (
    <UploadDropzone
      endpoint="/api/upload"
      validation={{ maxFileSize: '10MB', allowedTypes: ['image/*'] }}
      onUploadComplete={(results) => console.log(results)}
    />
  );
}

License

MIT