Extend dimahS3 with definePlugin — custom endpoints, lifecycle hooks, and typed context.

Use definePlugin to create reusable server extensions (like db()). Plugins can contribute lifecycle hooks, HTTP endpoints under your basePath, and typed instance context (s3[id]).

lib/s3-audit-plugin.ts

import { definePlugin, createS3Endpoint } from "@dimah-s3/server";

export const auditPlugin = definePlugin({
  id: "audit",
  hooks: {
    upload: {
      onConfirmed: async ({ key }) => {
        console.log("[audit] Upload confirmed:", key);
      },
    },
  },
  endpoints: {
    stats: createS3Endpoint("/audit/stats", { method: "GET" }, async () => ({
      status: "ok",
    })),
  },
  context: {
    log: (msg: string) => console.log("[audit]", msg),
  },
});

lib/s3.ts

import { dimahS3, route } from "@dimah-s3/server";
import { auditPlugin } from "./s3-audit-plugin";

export const s3 = dimahS3({
  client: awsS3,
  bucket: process.env.S3_BUCKET!,
  plugins: [auditPlugin],
  routes: {
    avatar: route({ upload: true }),
  },
});

// Access plugin context
s3.audit.log("Storage ready");

Hook execution order

Guards: Plugins execute first in registration order, followed by user config guards.
Lifecycle hooks (onConfirmed, onDeleted): User config hooks execute first, followed by plugin hooks.

Frequently asked questions

Use defineClientPlugin from @dimah-s3/core:

import { defineClientPlugin, pluginPath } from "@dimah-s3/core";

export function auditClient() {
  return defineClientPlugin({
    id: "audit",
    getActions: ($fetch) => ({
      getStats: () => $fetch(pluginPath("audit", "stats"), { method: "GET" }),
    }),
  });
}

Plugins

Hook execution order

Frequently asked questions

How do I create a client-side companion for my server plugin?

Can a route opt out of a global plugin?

On this page