mv-s3-manager/nextjs

Adattatore Next.js per la gestione di bucket S3-compatibili.

Fornisce factory per Route Handler dell'App Router, helper per Server Action e middleware opzionale per proteggere le route basate su S3.

Installazione

npm install mv-s3-manager/nextjs mv-s3-manager/core
# oppure
pnpm add mv-s3-manager/nextjs mv-s3-manager/core

Route Handler (App Router)

Gestore di upload

// app/api/upload/route.ts
import { createUploadHandler } from "mv-s3-manager/nextjs";
import type { S3ManagerConfig } from "mv-s3-manager/nextjs";
import { NextResponse } from "next/server";

const config: S3ManagerConfig = {
  region: "us-east-1",
  credentials: { accessKeyId: "...", secretAccessKey: "..." },
  bucket: "mio-bucket",
};

export const POST = createUploadHandler({
  config,
  authorize: async (req) => {
    const token = req.headers.get("x-api-key");
    if (token !== process.env.API_KEY) {
      return NextResponse.json({ errore: "Non autorizzato" }, { status: 401 });
    }
  },
});

Upload lato client (multipart):

const formData = new FormData();
formData.append("file", file);
await fetch("/api/upload?key=upload/foto.jpg", { method: "POST", body: formData });

Gestore di download

// app/api/files/[...key]/route.ts
import { createDownloadHandler } from "mv-s3-manager/nextjs";

export const GET = createDownloadHandler({
  config,
  resolveKey: (req) => req.nextUrl.pathname.replace("/api/files/", ""),
});

Gestore di URL prefirmati

// app/api/presign/route.ts — genera URL di download prefirmati
import { createPresignedUrlHandler } from "mv-s3-manager/nextjs";
export const GET = createPresignedUrlHandler({ config, expiresIn: 300 });

// app/api/presign-upload/route.ts — genera URL di upload prefirmati (per upload diretti lato client)
export const GET = createPresignedUrlHandler({ config, direction: "upload" });

Server Action

// lib/actions.ts
"use server";
import { createUploadAction, createPresignedUploadAction } from "mv-s3-manager/nextjs";

// Upload diretto attraverso il tuo server
export const caricaFile = createUploadAction({
  config,
  resolveKey: (fd) => `upload/${fd.get("nomeFile")}`,
});

// Upload diretto lato client (restituisce URL prefirmato)
export const getUploadUrl = createPresignedUploadAction({
  config,
  resolveKey: (fd) => `upload/${fd.get("nomeFile")}`,
  presignOptions: { expiresIn: 300 },
});

// app/upload/page.tsx
import { caricaFile } from "@/lib/actions";

export default function PaginaUpload() {
  return (
    <form action={caricaFile}>
      <input type="file" name="file" />
      <input type="hidden" name="nomeFile" value="foto.jpg" />
      <button type="submit">Carica</button>
    </form>
  );
}

Middleware

Proteggi le route con la validazione di token HMAC:

// middleware.ts
import { withS3Auth } from "mv-s3-manager/nextjs";
import type { NextRequest } from "next/server";
import { NextResponse } from "next/server";

function middleware(req: NextRequest) {
  return NextResponse.next();
}

export default withS3Auth(middleware, { secret: process.env.S3_AUTH_SECRET! });

export const config = {
  matcher: ["/api/files/:path*"],
};

Genera i token lato server da condividere con i client:

import { generateS3Token } from "mv-s3-manager/nextjs";

const token = await generateS3Token("immagini/foto.jpg", process.env.S3_AUTH_SECRET!);
// Passa il token al client — valido per 1 ora per default

Riferimento API

createUploadHandler(options)

| Opzione | Descrizione | |---|---| | config | S3ManagerConfig | | authorize? | Hook — restituisce NextResponse per interrompere | | resolveKey? | Estrae la chiave dalla richiesta. Default: parametro query ?key= | | uploadOptions? | Passato a uploadObject |

Accetta multipart/form-data (campo: "file") o un body grezzo nella richiesta.

createDownloadHandler(options)

Restituisce una risposta in streaming. Imposta Content-Type e Content-Length da S3. Restituisce 404 se la chiave non esiste.

Nota: Richiede il runtime Node.js (non Edge runtime) per la conversione dello stream.

createPresignedUrlHandler(options)

| Opzione | Tipo | Default | Descrizione | |---|---|---|---| | direction | "download" \| "upload" | "download" | Tipo di URL prefirmato | | expiresIn | number | 3600 | Scadenza in secondi | | uploadOptions | PresignedUploadUrlOptions | — | Usato solo con direction: "upload" |

createUploadAction(options)

Restituisce una Server Action (formData: FormData) => Promise<UploadActionResult>.

createPresignedUploadAction(options)

Restituisce una Server Action (formData: FormData) => Promise<{ url, key }>.

withS3Auth(handler, { secret })

Avvolge una funzione middleware con la validazione di token HMAC. I token vengono letti da ?token= o Authorization: Bearer <token>.

generateS3Token(key, secret, expiresIn?)

Genera un token HMAC-SHA256 che codifica chiave:scadenza. Da usare con withS3Auth.