nuxt-filer 0.0.15 → 0.0.17

package/README.md

@@ -9,7 +9,7 @@ File storage module for Nuxt. Provides a server-side `useFileStorage()` composab
 
 ## Features
 
-- **Pluggable provider architecture** — use the built-in unstorage provider or bring your own (Prisma, Drizzle, etc.)
+- **Pluggable provider architecture** — built-in unstorage (default), S3 and Drizzle providers, or bring your own
 - **File versioning** — built-in version tracking, latest-version filtering, and duplicate detection
 - **External file sync** — two-way sync with external systems (Jira, SharePoint, etc.) via optional provider interface
 - **Zero-config default** — works out of the box with local filesystem storage, no database required
@@ -17,6 +17,7 @@ File storage module for Nuxt. Provides a server-side `useFileStorage()` composab
 - **Group-based organization** — files are organized by `groupId` (project, ticket, order, etc.)
 - **`@nuxt/image` integration** — when `@nuxt/image` is installed, an IPX endpoint is wired up automatically so `<NuxtImg provider="filer" src="<groupId>/<id>" />` returns optimized variants of stored files
 - **Upload-time image processing** — optionally run images through Sharp when storing them (resize, format-convert, optimize, preserve animation) via a per-call `transform` option or the standalone `transformImage()` util
+- **Resumable uploads (tus)** — opt-in [tus](https://tus.io) endpoint backed by `@tus/server`, a client-side `useTusUpload()` composable, and `useTusStaging().promote()` to move finished uploads into the file storage
 
 ## Quick Setup
 
@@ -31,7 +32,8 @@ npx nuxi module add nuxt-filer
 export default defineNuxtConfig({
   modules: ['nuxt-filer'],
   filer: {
-    // Nitro storage mount name (default: 'documents')
+    // Nitro storage mount name (default: 'documents'). Mounted on the local fs
+    // for every provider unless you configure it yourself under `nitro.storage`.
     storageName: 'documents',
     // Base path for fs-lite driver (default: '.data/documents')
     storagePath: '.data/documents',
@@ -191,7 +193,141 @@ filer: {
 },
 ```
 
-`@nuxt/image` and `ipx` are declared as optional peer dependencies — they only need to be installed if you want to use this integration.
+`@nuxt/image` and `ipx` are declared as optional peer dependencies — they only need to be installed if you want to use this integration. Both ipx 3 and ipx 4 (pulled in by `@nuxt/image` 2.1+) are supported.
+
+### External image service (imgproxy / standalone IPX)
+
+Image processing can run in a separate service instead of this server, so
+`sharp` and `ipx` aren't needed here and one service can serve many apps:
+
+```ts
+filer: {
+  image: {
+    service: 'imgproxy', // or 'ipx' for a standalone `npx ipx serve`; default 'local'
+  },
+},
+```
+
+```bash
+NUXT_FILER_IMAGE_BASE_URL=https://img.example.com
+NUXT_FILER_IMAGE_KEY=...           # imgproxy signing key + salt (hex); unsigned URLs when unset
+NUXT_FILER_IMAGE_SALT=...
+NUXT_FILER_IMAGE_SOURCE_URL=http://app:3000   # how the service reaches this app
+```
+
+- `<NuxtImg provider="filer">` works unchanged. The image route redirects to a
+  signed service URL, so the signing key never reaches the browser.
+- The service fetches originals from `/_filer-ipx/_/<groupId>/<fileId>`, which
+  serves the stored bytes. `sourceURL` is the origin it uses for that — e.g. the
+  app's address on a private Docker network. Without it, the request's origin
+  is used.
+- Upload-time transforms (`upload(..., { transform })`) go through the service
+  too: the original is staged under the `_filer-transform` group, the variant
+  is fetched, and the staged copy is removed. This requires `sourceURL`.
+  `transformImage()` itself still needs `sharp`.
+- imgproxy receives the IPX modifiers translated to its options (`w`, `h`,
+  `s`, `fit`, `enlarge`, `q`, `f`, `b`, `pos`, `blur`, `sharpen`, `rotate`);
+  modifiers without an equivalent are dropped. A standalone IPX gets them as-is.
+- imgproxy blocks loopback and private source addresses by default. If
+  `sourceURL` points at one, set `IMGPROXY_ALLOW_LOOPBACK_SOURCE_ADDRESSES` /
+  `IMGPROXY_ALLOW_PRIVATE_SOURCE_ADDRESSES`. A standalone IPX needs the source
+  host in `--domains`.
+
+## Resumable uploads (tus)
+
+Large or flaky-network uploads can use the [tus protocol](https://tus.io)
+instead of a single multipart POST. Uploads are staged chunk-by-chunk into a
+local directory (survives connection drops and page reloads), then *promoted*
+into the regular file storage by one of your own server routes — which is
+where you enforce auth and attach domain metadata.
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['nuxt-filer'],
+  filer: {
+    tus: {
+      enabled: true,
+      route: '/_filer-tus',            // default
+      stagingDir: '.data/tus',         // default
+      maxSize: 500 * 1024 * 1024,      // optional, bytes
+      expiration: 24 * 60 * 60 * 1000, // optional: purge stale staged uploads
+    },
+  },
+})
+```
+
+Client side, the auto-imported `useTusUpload()` composable wraps
+[`tus-js-client`](https://github.com/tus/tus-js-client) with reactive state:
+
+```vue
+<script setup lang="ts">
+const tus = useTusUpload({
+  metadata: (file) => ({ comment: 'from the web app' }), // extra tus metadata
+  // cleanupOnPageHide: true,  // sendBeacon-delete staged uploads on close
+})
+
+function onSelect(e: Event) {
+  tus.add(Array.from((e.target as HTMLInputElement).files ?? []))
+}
+
+async function save() {
+  for (const item of tus.completed.value) {
+    await $fetch('/api/documents/finalize', {
+      method: 'POST',
+      body: { tusId: item.tusId, name: item.file.name },
+    })
+  }
+  tus.clear()
+}
+</script>
+```
+
+Each entry in `tus.items` tracks `progress`, `complete`, `tusId`, and `error`;
+`tus.remove(name)` aborts and deletes a staged upload, `tus.cancel()` discards
+everything. Interrupted uploads resume automatically (retry backoff, restart
+on `online`, and — via the tus fingerprint — across page reloads).
+
+Server side, promote a finished upload into the file storage:
+
+```ts
+// server/api/documents/finalize.post.ts
+export default defineEventHandler(async (event) => {
+  const body = await readBody(event)
+
+  const { id, meta } = await useTusStaging().promote(body.tusId, 'my-group', {
+    meta: { type: 'document' },        // merged over tus filename/filetype
+    // transform: { width: 1600 },     // optional sharp processing
+  })
+
+  return { id, meta }
+})
+```
+
+`useTusStaging()` also exposes `info()`, `read()`, and `remove()` for staged
+uploads. To protect or customize the endpoint itself (auth, upload hooks, a
+different datastore), configure the underlying `@tus/server` from a Nitro
+plugin — the server is created lazily on the first request:
+
+```ts
+// server/plugins/tus.ts
+export default defineNitroPlugin(() => {
+  setTusServerOptions({
+    async onIncomingRequest(req) {
+      // throw { status_code: 401, body: 'Unauthorized' } to reject
+    },
+  })
+})
+```
+
+Notes:
+
+- The endpoint handles the full tus lifecycle (create/HEAD/PATCH/DELETE); a
+  `POST <route>/cleanup` sub-route accepts `{ tusIds: string[] }` from
+  `navigator.sendBeacon` for page-close cleanup (used by `cleanupOnPageHide`).
+- Staging uses `@tus/file-store` on the local filesystem, independent of the
+  configured storage provider — promotion works with any provider, including
+  S3 and custom ones.
 
 ## S3 storage
 
@@ -226,9 +362,78 @@ export default defineNitroPlugin(() => {
 
 > `createS3Provider` requires the optional [`aws4fetch`](https://github.com/mhart/aws4fetch) peer dependency (`npm i aws4fetch`). Pass a custom `client` to use a different transport or to unit-test without network.
 
+## Drizzle (metadata in your database)
+
+`createDrizzleProvider` keeps file metadata in a table of your own
+[Drizzle](https://orm.drizzle.team) database and the bytes in a blob store —
+S3/R2 via `createS3Client()`, or any mounted Nitro storage. It uses only
+Drizzle's core query builder, so it works with every dialect and driver on
+Drizzle 0.36+ and v1.
+
+```ts
+// server/db/schema.ts
+import { pgTable, text, jsonb, timestamp, index } from 'drizzle-orm/pg-core'
+
+export const filerFiles = pgTable('filer_files', {
+  id: text('id').primaryKey(),
+  groupId: text('group_id').notNull(),
+  metadata: jsonb('metadata'),
+  createdAt: timestamp('created_at'), // optional
+  updatedAt: timestamp('updated_at'), // optional
+}, t => [index('filer_files_group_id_idx').on(t.groupId)])
+```
+
+```ts
+// server/plugins/file-provider.ts  (with `filer: { provider: 'custom' }`)
+import { db } from '../utils/db'
+import { filerFiles } from '../db/schema'
+
+export default defineNitroPlugin(() => {
+  const { s3 } = useRuntimeConfig()
+  setFileStorageProvider(createDrizzleProvider({
+    db,
+    table: filerFiles,
+    blobs: createS3Client({
+      accessKeyId: s3.accessKeyId,
+      secretAccessKey: s3.secretAccessKey,
+      endpoint: s3.endpoint,
+      bucket: s3.bucket,
+    }),
+    // or keep bytes on disk in the module's fs storage: blobs: 'documents'  (= `filer.storageName`)
+    // columns: { id: 'id', groupId: 'groupId', metadata: 'metadata', createdAt: 'createdAt', updatedAt: 'updatedAt' },
+  }))
+})
+```
+
+- `columns` maps to the table's schema property names, so an existing table can be used. `createdAt`/`updatedAt` are filled in when the table has them.
+- With a Postgres `jsonb` metadata column, `findByMeta()` (`@>`) and `update()` (`||` merge) run in the database — add a GIN index on `metadata` for large tables. Other column types and dialects filter and merge in JS.
+- Bytes are stored at `<groupId>/data/<id>`, the same layout as the S3 and unstorage providers, so moving metadata into a database keeps existing files readable.
+- Requires the optional `drizzle-orm` peer dependency.
+
+### Migrating from the unstorage provider
+
+Point `blobs` at the existing mount (`blobs: 'documents'`) so the bytes stay
+where they are, then copy the metadata sidecars into the table once —
+`importUnstorageMetadata` keeps ids and timestamps and skips rows that already
+exist, so re-running it is safe:
+
+```ts
+// server/tasks/filer/import.ts  (run with `nuxi task run filer:import`)
+import { db } from '../../utils/db'
+import { filerFiles } from '../../db/schema'
+
+export default defineTask({
+  meta: { description: 'Copy nuxt-filer metadata into the database' },
+  async run() {
+    const result = await importUnstorageMetadata({ from: 'documents', db, table: filerFiles })
+    return { result } // { imported, skipped }
+  },
+})
+```
+
 ## Custom Provider
 
-For advanced use cases (database-backed metadata, external file sync), implement the `FileStorageProvider` interface and register it in a Nitro plugin:
+For advanced use cases (other databases, external file sync), implement the `FileStorageProvider` interface and register it in a Nitro plugin:
 
 ```ts
 // nuxt.config.ts

package/dist/module.d.mts

@@ -12,6 +12,40 @@ interface FilerImageOptions {
     route?: string;
     /** Name to register the @nuxt/image provider under. Default: `filer`. */
     providerName?: string;
+    /**
+     * Where images are processed. `'local'` (default) runs IPX/sharp in this
+     * server. `'imgproxy'` or `'ipx'` (a standalone `ipx serve`) offload it: the
+     * image route redirects to the service, and upload-time transforms are
+     * fetched from it — so `sharp`/`ipx` aren't needed here.
+     */
+    service?: 'local' | 'imgproxy' | 'ipx';
+    /** Base URL of the image service. Runtime override: `NUXT_FILER_IMAGE_BASE_URL`. */
+    baseURL?: string;
+    /** imgproxy signing key (hex). Prefer `NUXT_FILER_IMAGE_KEY`. Unsigned URLs when unset. */
+    key?: string;
+    /** imgproxy signing salt (hex). Prefer `NUXT_FILER_IMAGE_SALT`. */
+    salt?: string;
+    /**
+     * Origin the service fetches originals from (e.g. `http://app:3000` on a
+     * private network). Defaults to the request origin; required for
+     * upload-time transforms. Runtime override: `NUXT_FILER_IMAGE_SOURCE_URL`.
+     */
+    sourceURL?: string;
+}
+interface FilerTusOptions {
+    /** Enable the tus endpoint + composable. Defaults to `true` when the `tus` option is an object. */
+    enabled?: boolean;
+    /** Base route of the tus endpoint. Default: `/_filer-tus`. */
+    route?: string;
+    /** Directory where in-progress uploads are staged. Default: `.data/tus`. */
+    stagingDir?: string;
+    /** Max upload size in bytes. Default: unlimited. */
+    maxSize?: number;
+    /**
+     * Staged uploads older than this (ms) are expired: reported to clients via
+     * `Upload-Expires` and purged periodically. Default: never expire.
+     */
+    expiration?: number;
 }
 interface ModuleOptions {
     /** Nitro storage mount name for binary file data. Default: 'documents' */
@@ -22,8 +56,10 @@ interface ModuleOptions {
     provider?: 'unstorage' | 'custom';
     /** @nuxt/image integration. Set to `false` to disable, or pass an object to override defaults. */
     image?: boolean | FilerImageOptions;
+    /** Resumable uploads via the tus protocol. Opt-in: pass `true` or an options object. */
+    tus?: boolean | FilerTusOptions;
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
 export { _default as default };
-export type { FilerImageOptions, ModuleOptions };
+export type { FilerImageOptions, FilerTusOptions, ModuleOptions };

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-filer",
   "configKey": "filer",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,5 +1,6 @@
-import { defineNuxtModule, createResolver, addServerImports, addImports, hasNuxtModule, addServerHandler, installModule } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, addServerImports, addImports, addServerHandler, hasNuxtModule, installModule } from '@nuxt/kit';
 import { consola } from 'consola';
+import { defu } from 'defu';
 
 const module = defineNuxtModule({
   meta: {
@@ -10,7 +11,8 @@ const module = defineNuxtModule({
     storageName: "documents",
     storagePath: ".data/documents",
     provider: "unstorage",
-    image: true
+    image: true,
+    tus: false
   },
   async setup(options, nuxt) {
     const resolver = createResolver(import.meta.url);
@@ -41,6 +43,18 @@ const module = defineNuxtModule({
       {
         name: "createS3Provider",
         from: resolver.resolve("./runtime/server/providers/s3")
+      },
+      {
+        name: "createS3Client",
+        from: resolver.resolve("./runtime/server/providers/s3")
+      },
+      {
+        name: "createDrizzleProvider",
+        from: resolver.resolve("./runtime/server/providers/drizzle")
+      },
+      {
+        name: "importUnstorageMetadata",
+        from: resolver.resolve("./runtime/server/providers/drizzle")
       }
     ]);
     const typesSpecifier = "nuxt-filer/runtime/types";
@@ -56,19 +70,65 @@ const module = defineNuxtModule({
       },
       { name: "ImageFormat", from: typesSpecifier, type: true },
       { name: "ImageTransformOptions", from: typesSpecifier, type: true },
-      { name: "ImageTransformResult", from: typesSpecifier, type: true }
+      { name: "ImageTransformResult", from: typesSpecifier, type: true },
+      { name: "TusUploadState", from: typesSpecifier, type: true },
+      { name: "UseTusUploadOptions", from: typesSpecifier, type: true },
+      { name: "TusPromoteOptions", from: typesSpecifier, type: true }
     ]);
+    const tusOpt = typeof options.tus === "object" && options.tus !== null ? options.tus : {};
+    const tusEnabled = options.tus === true || typeof options.tus === "object" && options.tus !== null && tusOpt.enabled !== false;
+    const tusRoute = (tusOpt.route ?? "/_filer-tus").replace(/\/+$/, "");
+    const tusStagingDir = tusOpt.stagingDir ?? ".data/tus";
+    if (tusEnabled) {
+      const tusHandler = resolver.resolve("./runtime/server/handlers/tus");
+      addServerHandler({ route: tusRoute, handler: tusHandler });
+      addServerHandler({ route: `${tusRoute}/**`, handler: tusHandler });
+      const tusUtilsSpecifier = resolver.resolve("./runtime/server/utils/tus");
+      addServerImports([
+        { name: "useTusServer", from: tusUtilsSpecifier },
+        { name: "setTusServerOptions", from: tusUtilsSpecifier },
+        { name: "useTusStaging", from: tusUtilsSpecifier }
+      ]);
+      addImports([
+        {
+          name: "useTusUpload",
+          from: resolver.resolve("./runtime/composables/tus")
+        }
+      ]);
+      nuxt.options.runtimeConfig.public.filer = defu(
+        nuxt.options.runtimeConfig.public.filer,
+        { tusRoute }
+      );
+    }
     const imageOpt = typeof options.image === "object" && options.image !== null ? options.image : {};
     const imageEnabled = options.image !== false && (imageOpt.enabled ?? true) !== false;
     const ipxRoute = (imageOpt.route ?? "/_filer-ipx").replace(/\/+$/, "");
     const providerName = imageOpt.providerName ?? "filer";
-    const shouldRegisterImage = imageEnabled && (imageOpt.enabled === "force" || hasNuxtModule("@nuxt/image"));
-    if (shouldRegisterImage) {
+    const imageService = imageEnabled ? imageOpt.service ?? "local" : "local";
+    if (imageService !== "local") {
+      const runtimeFiler = nuxt.options.runtimeConfig.filer ?? {};
+      runtimeFiler.image = defu(runtimeFiler.image, {
+        baseURL: imageOpt.baseURL ?? "",
+        key: imageOpt.key ?? "",
+        salt: imageOpt.salt ?? "",
+        sourceURL: imageOpt.sourceURL ?? ""
+      });
+      nuxt.options.runtimeConfig.filer = runtimeFiler;
       addServerHandler({
         route: `${ipxRoute}/**`,
-        handler: resolver.resolve("./runtime/server/handlers/ipx")
+        handler: resolver.resolve("./runtime/server/handlers/image-service")
       });
-      const imageConfig = nuxt.options.image ?? {};
+    }
+    const shouldRegisterImage = imageEnabled && (imageOpt.enabled === "force" || hasNuxtModule("@nuxt/image"));
+    if (shouldRegisterImage) {
+      if (imageService === "local") {
+        addServerHandler({
+          route: `${ipxRoute}/**`,
+          handler: resolver.resolve("./runtime/server/handlers/ipx")
+        });
+      }
+      const optionsWithImage = nuxt.options;
+      const imageConfig = optionsWithImage.image ?? {};
       const providers = imageConfig.providers ?? {};
       providers[providerName] = {
         name: providerName,
@@ -76,7 +136,7 @@ const module = defineNuxtModule({
         options: { baseURL: ipxRoute }
       };
       imageConfig.providers = providers;
-      nuxt.options.image = imageConfig;
+      optionsWithImage.image = imageConfig;
       const imageAlreadyLoaded = nuxt.options._installedModules?.some((m) => m.meta?.name === "@nuxt/image");
       if (imageAlreadyLoaded) {
         await installModule("@nuxt/image");
@@ -92,12 +152,21 @@ const module = defineNuxtModule({
         `export const storageName = ${JSON.stringify(options.storageName)};`,
         `export const storagePath = ${JSON.stringify(options.storagePath)};`
       ].join("\n");
-      nitroConfig.virtual["#nuxt-filer-image"] = `export const ipxRoute = ${JSON.stringify(ipxRoute)}`;
+      nitroConfig.virtual["#nuxt-filer-image"] = [
+        `export const ipxRoute = ${JSON.stringify(ipxRoute)};`,
+        `export const imageService = ${JSON.stringify(imageService)};`
+      ].join("\n");
+      nitroConfig.virtual["#nuxt-filer-tus"] = [
+        `export const tusRoute = ${JSON.stringify(tusRoute)};`,
+        `export const tusStagingDir = ${JSON.stringify(tusStagingDir)};`,
+        `export const tusMaxSize = ${JSON.stringify(tusOpt.maxSize ?? 0)};`,
+        `export const tusExpiration = ${JSON.stringify(tusOpt.expiration ?? 0)};`
+      ].join("\n");
+      nitroConfig.plugins = nitroConfig.plugins || [];
+      nitroConfig.plugins.push(
+        resolver.resolve("./runtime/server/plugins/default-storage")
+      );
       if (options.provider === "unstorage") {
-        nitroConfig.plugins = nitroConfig.plugins || [];
-        nitroConfig.plugins.push(
-          resolver.resolve("./runtime/server/plugins/default-storage")
-        );
         nitroConfig.plugins.push(
           resolver.resolve("./runtime/server/plugins/default-provider")
         );

package/dist/runtime/composables/tus.d.ts

@@ -0,0 +1,18 @@
+import type { TusUploadState, UseTusUploadOptions } from '../types.js';
+export type { TusUploadState, UseTusUploadOptions };
+/**
+ * Resumable uploads against the module's tus endpoint. Files are staged on
+ * the server; move them into the file storage afterwards with
+ * `useTusStaging().promote()` from one of your own server routes.
+ */
+export declare function useTusUpload(options?: UseTusUploadOptions): {
+    endpoint: string;
+    items: Record<string, TusUploadState>;
+    uploading: import("vue").ComputedRef<boolean>;
+    completed: import("vue").ComputedRef<TusUploadState[]>;
+    start: (file: File) => Promise<TusUploadState>;
+    add: (files: File | File[]) => void;
+    remove: (file: File | string) => Promise<void>;
+    clear: () => void;
+    cancel: () => Promise<void>;
+};

package/dist/runtime/composables/tus.js

@@ -0,0 +1,137 @@
+import { computed, reactive, getCurrentScope, onScopeDispose } from "vue";
+import { useRuntimeConfig } from "nuxt/app";
+import { Upload as TusUpload } from "tus-js-client";
+const DEFAULT_RETRY_DELAYS = [0, 3e3, 5e3, 1e4, 2e4];
+export function useTusUpload(options = {}) {
+  const runtimeConfig = useRuntimeConfig();
+  const endpoint = options.endpoint ?? runtimeConfig.public.filer?.tusRoute ?? "/_filer-tus";
+  const items = reactive({});
+  const instances = /* @__PURE__ */ new Map();
+  const uploading = computed(
+    () => Object.values(items).some((item) => !item.complete && !item.error)
+  );
+  const completed = computed(
+    () => Object.values(items).filter((item) => item.complete)
+  );
+  function captureUploadUrl(state, upload) {
+    if (upload.url && !state.tusId) {
+      state.uploadUrl = upload.url;
+      state.tusId = upload.url.split("/").pop();
+    }
+  }
+  async function start(file) {
+    const key = file.name;
+    const state = { file, progress: 0, complete: false };
+    items[key] = state;
+    const upload = new TusUpload(file, {
+      endpoint,
+      retryDelays: options.retryDelays ?? DEFAULT_RETRY_DELAYS,
+      chunkSize: options.chunkSize,
+      removeFingerprintOnSuccess: true,
+      metadata: {
+        filename: file.name,
+        filetype: file.type,
+        ...options.metadata?.(file)
+      },
+      onError(error) {
+        const item = items[key];
+        if (!item) return;
+        item.error = error instanceof Error ? error.message : String(error);
+        options.onError?.(file, error);
+      },
+      onProgress(bytesUploaded, bytesTotal) {
+        const item = items[key];
+        if (!item) return;
+        item.progress = bytesTotal ? bytesUploaded / bytesTotal * 100 : 0;
+        captureUploadUrl(item, upload);
+      },
+      onSuccess() {
+        const item = items[key];
+        if (!item) return;
+        captureUploadUrl(item, upload);
+        item.progress = 100;
+        item.complete = true;
+        options.onSuccess?.(file, item);
+      }
+    });
+    instances.set(key, upload);
+    if (options.resume !== false) {
+      const previous = await upload.findPreviousUploads().catch(() => []);
+      if (previous[0]) upload.resumeFromPreviousUpload(previous[0]);
+    }
+    upload.start();
+    return state;
+  }
+  function add(files) {
+    for (const file of Array.isArray(files) ? files : [files]) {
+      if (!items[file.name]) void start(file);
+    }
+  }
+  async function remove(file) {
+    const key = typeof file === "string" ? file : file.name;
+    const state = items[key];
+    const upload = instances.get(key);
+    instances.delete(key);
+    Reflect.deleteProperty(items, key);
+    if (upload) {
+      await upload.abort(true).catch(() => {
+      });
+    } else if (state?.uploadUrl) {
+      await fetch(state.uploadUrl, {
+        method: "DELETE",
+        headers: { "Tus-Resumable": "1.0.0" }
+      }).catch(() => {
+      });
+    }
+  }
+  function clear() {
+    for (const upload of instances.values()) {
+      void upload.abort().catch(() => {
+      });
+    }
+    instances.clear();
+    for (const key of Object.keys(items)) Reflect.deleteProperty(items, key);
+  }
+  async function cancel() {
+    await Promise.allSettled(Object.keys(items).map((key) => remove(key)));
+  }
+  if (import.meta.client) {
+    const onOnline = () => {
+      for (const [key, upload] of instances) {
+        const item = items[key];
+        if (item && !item.complete) {
+          item.error = void 0;
+          upload.start();
+        }
+      }
+    };
+    const onPageHide = () => {
+      if (!options.cleanupOnPageHide) return;
+      const tusIds = Object.values(items).map((item) => item.tusId).filter((id) => !!id);
+      if (tusIds.length === 0) return;
+      navigator.sendBeacon(
+        `${endpoint}/cleanup`,
+        new Blob([JSON.stringify({ tusIds })], { type: "application/json" })
+      );
+    };
+    window.addEventListener("online", onOnline);
+    window.addEventListener("pagehide", onPageHide);
+    if (getCurrentScope()) {
+      onScopeDispose(() => {
+        window.removeEventListener("online", onOnline);
+        window.removeEventListener("pagehide", onPageHide);
+      });
+    }
+  }
+  return {
+    endpoint,
+    items,
+    uploading,
+    completed,
+    start,
+    add,
+    remove,
+    clear,
+    cancel
+  };
+}

package/dist/runtime/server/handlers/image-service.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Image route for an external service (imgproxy / standalone IPX). Same URL
+ * shape as the local IPX route — `<route>/<modifiers>/<groupId>/<id>` — so the
+ * `@nuxt/image` provider is unchanged:
+ *
+ * - `_` (no modifiers) serves the stored original. This is what the service
+ *   fetches as its source.
+ * - anything else redirects to the service, so signing keys stay server-side
+ *   and this server never loads sharp/IPX.
+ */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void | Buffer<ArrayBufferLike> | null>>;
+export default _default;

package/dist/runtime/server/handlers/image-service.js

@@ -0,0 +1,21 @@
+import { defineEventHandler, createError, getRequestURL, sendRedirect, setResponseHeader } from "h3";
+import { ipxRoute } from "#nuxt-filer-image";
+import { sendStoredFile } from "../utils/send.js";
+import { imageServiceURL, parseModifiers, sourceURL } from "../utils/image-service.js";
+import { useImageService } from "../utils/image-service-runtime.js";
+export default defineEventHandler(async (event) => {
+  const path = event.path.slice(ipxRoute.length).split("?")[0].replace(/^\/+/, "");
+  const [modifiers = "", ...segments] = path.split("/");
+  const parts = segments.filter(Boolean).map(decodeURIComponent);
+  if (parts.length < 2) {
+    throw createError({ statusCode: 404, statusMessage: "Image not found" });
+  }
+  const id = parts.pop();
+  const groupId = parts.join("/");
+  if (modifiers === "_") return sendStoredFile(event, groupId, id);
+  const config = useImageService();
+  const origin = config.sourceURL ?? getRequestURL(event).origin;
+  const url = await imageServiceURL(config, parseModifiers(modifiers), sourceURL(config, origin, groupId, id));
+  setResponseHeader(event, "cache-control", "public, max-age=86400");
+  return sendRedirect(event, url, 302);
+});