nuxt-filer 0.0.6 → 0.0.9

package/README.md

@@ -16,6 +16,7 @@ File storage module for Nuxt. Provides a server-side `useFileStorage()` composab
 - **Auto-imported** — `useFileStorage()`, types, and provider utilities are auto-imported in server context
 - **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
 
 ## Quick Setup
 
@@ -76,11 +77,49 @@ export default defineEventHandler(async (event) => {
 })
 ```
 
+### Upload-time image processing
+
+Pass a `transform` option to `upload()` to process an image **before it is stored** — useful for normalizing user uploads or rehosted remote images to a capped size and compact format. The processed bytes are what gets stored, and the file's `meta.mime` / `meta.width` / `meta.height` are updated to match the result.
+
+```ts
+const id = await storage.upload(groupId, file.data, {
+  meta: { name: file.filename!, mime: file.type!, type: 'image', version: 1 },
+  transform: {
+    width: 128,
+    height: 128,
+    format: 'webp', // convert to webp
+    // fit: 'inside' (default), withoutEnlargement: true (default),
+    // quality, background, animated (default true)
+  },
+})
+```
+
+You can also call the util directly (e.g. for images fetched server-side):
+
+```ts
+const res = await transformImage(buffer, { width: 64, format: 'webp' })
+// res: { data: Buffer, mime: 'image/webp', format: 'webp', width: 64, height: 64 }
+```
+
+**`transform` / `transformImage()` options**
+
+| Option | Description |
+|---|---|
+| `width`, `height` | Target box in px (combined with `fit`) |
+| `fit` | Resize fit mode (`inside` default, or `cover`/`contain`/`fill`/`outside`) |
+| `withoutEnlargement` | Never scale up beyond the original (default `true`) |
+| `format` | Output format: `webp` / `png` / `jpeg` / `avif` / `gif` (default: keep input) |
+| `quality` | Output quality `1-100` for lossy formats |
+| `animated` | Preserve all frames of animated inputs (default `true`; only retained when `format` is `webp`/`gif`) |
+| `background` | Background used when flattening transparency |
+
+> Image processing requires the optional [`sharp`](https://sharp.pixelplumbing.com/) peer dependency. Install it (`npm i sharp`) only if you use `transform` / `transformImage()` — calling them without `sharp` throws a clear error. Without a `transform`, `upload()` stores the raw bytes unchanged and needs no extra dependency.
+
 ### `useFileStorage()` API
 
 | Method | Description |
 |---|---|
-| `upload(groupId, data, options?)` | Store a file, returns its ID |
+| `upload(groupId, data, options?)` | Store a file, returns its ID. `options.transform` runs the bytes through Sharp first (see above) |
 | `list(groupId)` | List all files in a group |
 | `get(groupId, id)` | Get a file with data and metadata |
 | `getData(groupId, id)` | Get raw binary data only |

package/dist/module.json

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

package/dist/module.mjs

@@ -18,6 +18,10 @@ const module = defineNuxtModule({
       {
         name: "useFileStorage",
         from: resolver.resolve("./runtime/server/utils/storage")
+      },
+      {
+        name: "transformImage",
+        from: resolver.resolve("./runtime/server/utils/image")
       }
     ]);
     const providerSpecifier = resolver.resolve("./runtime/server/provider");
@@ -41,7 +45,10 @@ const module = defineNuxtModule({
         name: "FileStorageExternalProvider",
         from: typesSpecifier,
         type: true
-      }
+      },
+      { name: "ImageFormat", from: typesSpecifier, type: true },
+      { name: "ImageTransformOptions", from: typesSpecifier, type: true },
+      { name: "ImageTransformResult", from: typesSpecifier, type: true }
     ]);
     const imageOpt = typeof options.image === "object" && options.image !== null ? options.image : {};
     const imageEnabled = options.image !== false && (imageOpt.enabled ?? true) !== false;
@@ -73,15 +80,16 @@ const module = defineNuxtModule({
     }
     nuxt.hook("nitro:config", (nitroConfig) => {
       nitroConfig.virtual = nitroConfig.virtual || {};
-      nitroConfig.virtual["#nuxt-filer-options"] = `export const storageName = ${JSON.stringify(options.storageName)}`;
+      nitroConfig.virtual["#nuxt-filer-options"] = [
+        `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)}`;
       if (options.provider === "unstorage") {
-        nitroConfig.storage = nitroConfig.storage || {};
-        nitroConfig.storage[options.storageName] = {
-          driver: "fsLite",
-          base: options.storagePath
-        };
         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/image/provider.d.ts

@@ -3,5 +3,10 @@ interface FilerProviderOptions {
     baseURL?: string;
 }
 export declare const getImage: ProviderGetImage;
-export declare const validateDomains = false;
+declare const _default: () => {
+    getImage: ProviderGetImage;
+    validateDomains: boolean;
+    supportsAlias: boolean;
+};
+export default _default;
 export type { FilerProviderOptions };

package/dist/runtime/image/provider.js

@@ -1,17 +1,35 @@
+import { joinURL } from "ufo";
 const operationsGenerator = (modifiers) => {
-  const ops = [];
-  for (const [key, value] of Object.entries(modifiers)) {
+  const out = [];
+  if (modifiers.width && modifiers.height) {
+    modifiers.resize = `${modifiers.width}x${modifiers.height}`;
+    delete modifiers.width;
+    delete modifiers.height;
+  }
+  const keyMap = {
+    format: "f",
+    width: "w",
+    height: "h",
+    resize: "s",
+    quality: "q",
+    background: "b",
+    position: "pos"
+  };
+  for (const [rawKey, value] of Object.entries(modifiers)) {
     if (value === void 0 || value === null || value === "" || value === false) continue;
-    ops.push(`${key}_${value}`);
+    const key = keyMap[rawKey] ?? rawKey;
+    out.push(`${key}_${value}`);
   }
-  return ops.length ? ops.join(",") : "_";
+  return out.length ? out.join(",") : "_";
 };
-export const getImage = (src, { modifiers = {}, baseURL } = {}) => {
-  const root = (baseURL ?? "/_filer-ipx").replace(/\/+$/, "");
+export const getImage = (src, { modifiers = {}, baseURL = "/_filer-ipx" } = {}) => {
   const ops = operationsGenerator(
     modifiers
   );
-  const path = src.replace(/^\/+/, "");
-  return { url: `${root}/${ops}/${path}` };
+  return { url: joinURL(baseURL, ops, src.replace(/^\/+/, "")) };
 };
-export const validateDomains = false;
+export default () => ({
+  getImage,
+  validateDomains: false,
+  supportsAlias: false
+});

package/dist/runtime/server/drivers/fs.d.ts

@@ -0,0 +1,34 @@
+export interface FsDriverOptions {
+    /** Filesystem path used as the base for all keys. Required. */
+    base?: string;
+    /** Treat the storage as read-only; writes become no-ops. */
+    readOnly?: boolean;
+    /** Suppress `clear()`. */
+    noClear?: boolean;
+    /** Optional ignore filter applied during `getKeys`. */
+    ignore?: (path: string) => boolean;
+}
+export default function fsDriver(opts?: FsDriverOptions): {
+    name: string;
+    options: FsDriverOptions;
+    flags: {
+        maxDepth: boolean;
+    };
+    hasItem(key: string): boolean;
+    getItem(key: string): Promise<string | null>;
+    getItemRaw(key: string): Promise<Buffer<ArrayBufferLike> | null>;
+    getMeta(key: string): Promise<{
+        atime: Date | undefined;
+        mtime: Date | undefined;
+        size: number | undefined;
+        birthtime: Date | undefined;
+        ctime: Date | undefined;
+    }>;
+    setItem(key: string, value: string): Promise<void>;
+    setItemRaw(key: string, value: Buffer | Uint8Array): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    getKeys(_base?: string, topts?: {
+        maxDepth?: number;
+    }): Promise<string[]>;
+    clear(): Promise<void>;
+};

package/dist/runtime/server/drivers/fs.js

@@ -0,0 +1,106 @@
+import {
+  existsSync,
+  promises as fsp
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+const PATH_TRAVERSE_RE = /\.\.:|\.\.$/;
+const DRIVER_NAME = "nuxt-filer-fs";
+function driverError(message) {
+  return new Error(`[nuxt-filer] [${DRIVER_NAME}] ${message}`);
+}
+function ignoreNotfound(err) {
+  if (err.code === "ENOENT" || err.code === "EISDIR") return null;
+  throw err;
+}
+async function readdirSafe(dir) {
+  try {
+    return await fsp.readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+}
+async function readdirRecursive(dir, ignore, maxDepth) {
+  if (ignore && ignore(dir)) return [];
+  const entries = await readdirSafe(dir);
+  const files = [];
+  await Promise.all(
+    entries.map(async (entry) => {
+      const entryPath = resolve(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (maxDepth === void 0 || maxDepth > 0) {
+          const nested = await readdirRecursive(
+            entryPath,
+            ignore,
+            maxDepth === void 0 ? void 0 : maxDepth - 1
+          );
+          files.push(...nested.map((f) => entry.name + "/" + f));
+        }
+      } else if (!(ignore && ignore(entry.name))) {
+        files.push(entry.name);
+      }
+    })
+  );
+  return files;
+}
+export default function fsDriver(opts = {}) {
+  if (!opts.base) {
+    throw driverError("Missing required option `base`.");
+  }
+  const base = resolve(opts.base);
+  const r = (key) => {
+    if (PATH_TRAVERSE_RE.test(key)) {
+      throw driverError(
+        `Invalid key: ${JSON.stringify(key)}. It should not contain .. segments`
+      );
+    }
+    return join(base, key.replace(/:/g, "/"));
+  };
+  async function write(path, value) {
+    await fsp.mkdir(dirname(path), { recursive: true });
+    await fsp.writeFile(path, value);
+  }
+  return {
+    name: DRIVER_NAME,
+    options: opts,
+    flags: { maxDepth: true },
+    hasItem(key) {
+      return existsSync(r(key));
+    },
+    getItem(key) {
+      return fsp.readFile(r(key), "utf8").catch((err) => ignoreNotfound(err));
+    },
+    getItemRaw(key) {
+      return fsp.readFile(r(key)).catch((err) => ignoreNotfound(err));
+    },
+    async getMeta(key) {
+      const stat = await fsp.stat(r(key)).catch(() => ({}));
+      return {
+        atime: stat.atime,
+        mtime: stat.mtime,
+        size: stat.size,
+        birthtime: stat.birthtime,
+        ctime: stat.ctime
+      };
+    },
+    async setItem(key, value) {
+      if (opts.readOnly) return;
+      await write(r(key), value);
+    },
+    async setItemRaw(key, value) {
+      if (opts.readOnly) return;
+      await write(r(key), value);
+    },
+    async removeItem(key) {
+      if (opts.readOnly) return;
+      await fsp.unlink(r(key)).catch((err) => ignoreNotfound(err));
+    },
+    getKeys(_base, topts) {
+      return readdirRecursive(r("."), opts.ignore, topts?.maxDepth);
+    },
+    async clear() {
+      if (opts.readOnly || opts.noClear) return;
+      await fsp.rm(r("."), { recursive: true, force: true });
+    }
+  };
+}

package/dist/runtime/server/plugins/default-storage.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Mount the default filesystem-backed storage for nuxt-filer. We mount
+ * via a Nitro plugin rather than `nitroConfig.storage` so that our
+ * custom fs driver is bundled with the plugin and there is no runtime
+ * module resolution against the package's `dist/`.
+ */
+declare const _default: import("nitropack/types").NitroAppPlugin;
+export default _default;

package/dist/runtime/server/plugins/default-storage.js

@@ -0,0 +1,7 @@
+import { defineNitroPlugin, useStorage } from "nitropack/runtime";
+import { storageName, storagePath } from "#nuxt-filer-options";
+import fsDriver from "../drivers/fs.js";
+export default defineNitroPlugin(() => {
+  const storage = useStorage();
+  storage.mount(storageName, fsDriver({ base: storagePath }));
+});

package/dist/runtime/server/utils/image.d.ts

@@ -0,0 +1,11 @@
+import type { ImageFormat, ImageTransformOptions, ImageTransformResult } from '../../../runtime/types.js';
+export type { ImageFormat, ImageTransformOptions, ImageTransformResult };
+/**
+ * Process an image buffer with sharp: resize within a box, convert format,
+ * optimize, and (by default) preserve animation for multi-frame inputs. Used
+ * for upload-time normalization — see `useFileStorage().upload({ transform })`.
+ *
+ * Requires the optional `sharp` peer dependency; throws a clear error if it is
+ * not installed.
+ */
+export declare function transformImage(data: Buffer | Uint8Array, options?: ImageTransformOptions): Promise<ImageTransformResult>;

package/dist/runtime/server/utils/image.js

@@ -0,0 +1,50 @@
+const MIME_BY_FORMAT = {
+  webp: "image/webp",
+  png: "image/png",
+  jpeg: "image/jpeg",
+  jpg: "image/jpeg",
+  avif: "image/avif",
+  gif: "image/gif"
+};
+let sharpModule;
+async function loadSharp() {
+  if (sharpModule) return sharpModule;
+  try {
+    sharpModule = (await import("sharp")).default;
+  } catch {
+    throw new Error(
+      "[nuxt-filer] Image transforms require the optional peer dependency `sharp`. Install it with `npm i sharp`."
+    );
+  }
+  return sharpModule;
+}
+export async function transformImage(data, options = {}) {
+  const sharp = await loadSharp();
+  const animated = options.animated ?? true;
+  let pipeline = sharp(data, { animated });
+  if (options.width != null || options.height != null) {
+    pipeline = pipeline.resize({
+      width: options.width,
+      height: options.height,
+      fit: options.fit ?? "inside",
+      withoutEnlargement: options.withoutEnlargement ?? true,
+      background: options.background
+    });
+  }
+  if (options.format) {
+    const formatOptions = options.quality != null ? { quality: options.quality } : {};
+    pipeline = pipeline.toFormat(
+      options.format,
+      formatOptions
+    );
+  }
+  const out = await pipeline.toBuffer({ resolveWithObject: true });
+  const format = out.info.format;
+  return {
+    data: out.data,
+    format,
+    mime: MIME_BY_FORMAT[format] ?? `image/${format}`,
+    width: out.info.width,
+    height: out.info.height
+  };
+}

package/dist/runtime/server/utils/storage.d.ts

@@ -1,8 +1,9 @@
-import type { FileMeta, StoredFile, ExternalRef, FileStorageProvider } from '../../../runtime/types.js';
-export type { FileMeta, StoredFile, ExternalRef, FileStorageProvider };
+import type { FileMeta, StoredFile, ExternalRef, FileStorageProvider, ImageTransformOptions, ImageTransformResult } from '../../../runtime/types.js';
+export type { FileMeta, StoredFile, ExternalRef, FileStorageProvider, ImageTransformOptions, ImageTransformResult, };
 export declare const useFileStorage: () => {
     upload: (groupId: string, data: Buffer | Uint8Array, options?: {
         meta?: FileMeta;
+        transform?: ImageTransformOptions;
     }) => Promise<string>;
     list: (groupId: string) => Promise<StoredFile[]>;
     get: (groupId: string, id: string) => Promise<StoredFile | null>;

package/dist/runtime/server/utils/storage.js

@@ -1,9 +1,20 @@
 import { defu } from "defu";
 import { useFileStorageProvider } from "../provider.js";
+import { transformImage } from "./image.js";
 export const useFileStorage = () => {
   const provider = useFileStorageProvider();
   async function upload(groupId, data, options = {}) {
-    const { id } = await provider.create(groupId, data, options.meta);
+    let payload = data;
+    if (options.transform) {
+      const result = await transformImage(data, options.transform);
+      payload = result.data;
+      if (options.meta) {
+        options.meta.mime = result.mime;
+        options.meta.width = result.width;
+        options.meta.height = result.height;
+      }
+    }
+    const { id } = await provider.create(groupId, payload, options.meta);
     return id;
   }
   async function list(groupId) {

package/dist/runtime/types.d.ts

@@ -7,6 +7,51 @@ export interface FileMeta {
     comment?: string;
     [key: string]: unknown;
 }
+/** Output image format for {@link transformImage}. */
+export type ImageFormat = 'webp' | 'png' | 'jpeg' | 'avif' | 'gif';
+/**
+ * Options for upload-time image processing, backed by the optional `sharp`
+ * peer dependency. Passed via `useFileStorage().upload(.., { transform })` or
+ * to the standalone `transformImage()` util.
+ */
+export interface ImageTransformOptions {
+    /** Target width in px. Combined with `fit` to bound the image. */
+    width?: number;
+    /** Target height in px. Combined with `fit` to bound the image. */
+    height?: number;
+    /**
+     * How the image is resized to fit `width`/`height`. Mirrors sharp's `fit`.
+     * Default: `'inside'` (preserve aspect ratio, fit within the box).
+     */
+    fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+    /** Never scale the image up beyond its original size. Default: `true`. */
+    withoutEnlargement?: boolean;
+    /** Output format. Default: keep the input's format. */
+    format?: ImageFormat;
+    /** Output quality (1-100) for lossy formats (webp/jpeg/avif). */
+    quality?: number;
+    /**
+     * Preserve every frame of multi-frame inputs (animated webp/gif). Default:
+     * `true`; harmless for static images. Animation is only retained when the
+     * output `format` is animation-capable (`webp`/`gif`).
+     */
+    animated?: boolean;
+    /** Background used when flattening transparency (e.g. for `contain`/jpeg). */
+    background?: string;
+}
+/** Result of {@link transformImage}: the processed bytes plus resolved metadata. */
+export interface ImageTransformResult {
+    /** The processed image bytes. */
+    data: Buffer;
+    /** MIME type of the processed image, e.g. `image/webp`. */
+    mime: string;
+    /** Resolved output format, e.g. `webp`. */
+    format: string;
+    /** Width of the processed image in px, if sharp could determine it. */
+    width?: number;
+    /** Height of the processed image in px, if sharp could determine it. */
+    height?: number;
+}
 export interface ExternalRef {
     /** External system identifier, e.g. 'jira', 'sharepoint' */
     source: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-filer",
-  "version": "0.0.6",
+  "version": "0.0.9",
   "description": "File storage module for Nuxt",
   "repository": {
     "type": "git",
@@ -64,13 +64,15 @@
     "eslint": "^10.1.0",
     "ipx": "^3.1.1",
     "nuxt": "^4.4.2",
+    "sharp": "^0.34.5",
     "typescript": "~6.0.2",
     "vitest": "^4.1.2",
     "vue-tsc": "^3.2.6"
   },
   "peerDependencies": {
     "@nuxt/image": "^2.0.0",
-    "ipx": "^3.0.0"
+    "ipx": "^3.0.0",
+    "sharp": "^0.33.0 || ^0.34.0"
   },
   "peerDependenciesMeta": {
     "@nuxt/image": {
@@ -78,12 +80,16 @@
     },
     "ipx": {
       "optional": true
+    },
+    "sharp": {
+      "optional": true
     }
   },
   "packageManager": "pnpm@10.33.0",
   "pnpm": {
     "onlyBuiltDependencies": [
-      "esbuild"
+      "esbuild",
+      "sharp"
     ]
   }
 }

package/src/runtime/image/provider.ts

@@ -1,4 +1,5 @@
 import type { ProviderGetImage } from '@nuxt/image';
+import { joinURL } from 'ufo';
 
 interface FilerProviderOptions {
   baseURL?: string;
@@ -7,27 +8,44 @@ interface FilerProviderOptions {
 const operationsGenerator = (
   modifiers: Record<string, string | number | boolean | undefined>
 ): string => {
-  const ops: string[] = [];
-  for (const [key, value] of Object.entries(modifiers)) {
+  const out: string[] = [];
+  // Match @nuxt/image's built-in IPX provider: width+height collapses to resize.
+  if (modifiers.width && modifiers.height) {
+    modifiers.resize = `${modifiers.width}x${modifiers.height}`;
+    delete modifiers.width;
+    delete modifiers.height;
+  }
+  const keyMap: Record<string, string> = {
+    format: 'f',
+    width: 'w',
+    height: 'h',
+    resize: 's',
+    quality: 'q',
+    background: 'b',
+    position: 'pos',
+  };
+  for (const [rawKey, value] of Object.entries(modifiers)) {
     if (value === undefined || value === null || value === '' || value === false) continue;
-    ops.push(`${key}_${value}`);
+    const key = keyMap[rawKey] ?? rawKey;
+    out.push(`${key}_${value}`);
   }
-  return ops.length ? ops.join(',') : '_';
+  return out.length ? out.join(',') : '_';
 };
 
 export const getImage: ProviderGetImage = (
   src: string,
-  { modifiers = {}, baseURL }: { modifiers?: Record<string, unknown>; baseURL?: string } = {},
-  // ctx is provided by @nuxt/image but unused here
+  { modifiers = {}, baseURL = '/_filer-ipx' }: { modifiers?: Record<string, unknown>; baseURL?: string } = {},
 ) => {
-  const root = (baseURL ?? '/_filer-ipx').replace(/\/+$/, '');
   const ops = operationsGenerator(
     modifiers as Record<string, string | number | boolean | undefined>
   );
-  const path = src.replace(/^\/+/, '');
-  return { url: `${root}/${ops}/${path}` };
+  return { url: joinURL(baseURL, ops, src.replace(/^\/+/, '')) };
 };
 
-export const validateDomains = false;
+export default () => ({
+  getImage,
+  validateDomains: false,
+  supportsAlias: false,
+});
 
 export type { FilerProviderOptions };

package/src/runtime/server/drivers/fs.ts

@@ -0,0 +1,156 @@
+import {
+  existsSync,
+  promises as fsp,
+  type Dirent,
+  type Stats,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+/**
+ * Drop-in replacement for unstorage's built-in `fs-lite` driver.
+ *
+ * `fs-lite` creates intermediate directories via a userspace `ensuredir`
+ * (recursive `existsSync` + non-recursive `mkdir`). In practice this is
+ * unreliable for first-time writes to a brand-new key path — we observed
+ * ENOENT on `writeFile` even though `ensuredir` should have run. The
+ * kernel's atomic `mkdir(..., { recursive: true })` is much more reliable
+ * across filesystems (including container-bound volumes).
+ *
+ * This driver mirrors the fs-lite public surface but always pre-creates
+ * the parent directory tree with a single recursive `mkdir` before any
+ * write, and tolerates missing files / dirs on reads.
+ *
+ * Implemented against unstorage's structural `Driver` contract; we avoid
+ * importing `defineDriver` so this stays decoupled from a specific
+ * unstorage major.
+ */
+
+const PATH_TRAVERSE_RE = /\.\.:|\.\.$/;
+const DRIVER_NAME = 'nuxt-filer-fs';
+
+export interface FsDriverOptions {
+  /** Filesystem path used as the base for all keys. Required. */
+  base?: string;
+  /** Treat the storage as read-only; writes become no-ops. */
+  readOnly?: boolean;
+  /** Suppress `clear()`. */
+  noClear?: boolean;
+  /** Optional ignore filter applied during `getKeys`. */
+  ignore?: (path: string) => boolean;
+}
+
+function driverError(message: string): Error {
+  return new Error(`[nuxt-filer] [${DRIVER_NAME}] ${message}`);
+}
+
+function ignoreNotfound<T>(err: NodeJS.ErrnoException): T | null {
+  if (err.code === 'ENOENT' || err.code === 'EISDIR') return null;
+  throw err;
+}
+
+async function readdirSafe(dir: string): Promise<Dirent[]> {
+  try {
+    return await fsp.readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw err;
+  }
+}
+
+async function readdirRecursive(
+  dir: string,
+  ignore: ((p: string) => boolean) | undefined,
+  maxDepth: number | undefined,
+): Promise<string[]> {
+  if (ignore && ignore(dir)) return [];
+  const entries = await readdirSafe(dir);
+  const files: string[] = [];
+  await Promise.all(
+    entries.map(async (entry) => {
+      const entryPath = resolve(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (maxDepth === undefined || maxDepth > 0) {
+          const nested = await readdirRecursive(
+            entryPath,
+            ignore,
+            maxDepth === undefined ? undefined : maxDepth - 1,
+          );
+          files.push(...nested.map((f) => entry.name + '/' + f));
+        }
+      } else if (!(ignore && ignore(entry.name))) {
+        files.push(entry.name);
+      }
+    }),
+  );
+  return files;
+}
+
+export default function fsDriver(opts: FsDriverOptions = {}) {
+  if (!opts.base) {
+    throw driverError('Missing required option `base`.');
+  }
+  const base = resolve(opts.base);
+
+  const r = (key: string) => {
+    if (PATH_TRAVERSE_RE.test(key)) {
+      throw driverError(
+        `Invalid key: ${JSON.stringify(key)}. It should not contain .. segments`,
+      );
+    }
+    return join(base, key.replace(/:/g, '/'));
+  };
+
+  async function write(path: string, value: string | Buffer | Uint8Array) {
+    await fsp.mkdir(dirname(path), { recursive: true });
+    await fsp.writeFile(path, value);
+  }
+
+  return {
+    name: DRIVER_NAME,
+    options: opts,
+    flags: { maxDepth: true },
+
+    hasItem(key: string) {
+      return existsSync(r(key));
+    },
+    getItem(key: string) {
+      return fsp
+        .readFile(r(key), 'utf8')
+        .catch((err) => ignoreNotfound<string>(err));
+    },
+    getItemRaw(key: string) {
+      return fsp
+        .readFile(r(key))
+        .catch((err) => ignoreNotfound<Buffer>(err));
+    },
+    async getMeta(key: string) {
+      const stat = (await fsp.stat(r(key)).catch(() => ({}))) as Partial<Stats>;
+      return {
+        atime: stat.atime,
+        mtime: stat.mtime,
+        size: stat.size,
+        birthtime: stat.birthtime,
+        ctime: stat.ctime,
+      };
+    },
+    async setItem(key: string, value: string) {
+      if (opts.readOnly) return;
+      await write(r(key), value);
+    },
+    async setItemRaw(key: string, value: Buffer | Uint8Array) {
+      if (opts.readOnly) return;
+      await write(r(key), value);
+    },
+    async removeItem(key: string) {
+      if (opts.readOnly) return;
+      await fsp.unlink(r(key)).catch((err) => ignoreNotfound(err));
+    },
+    getKeys(_base?: string, topts?: { maxDepth?: number }) {
+      return readdirRecursive(r('.'), opts.ignore, topts?.maxDepth);
+    },
+    async clear() {
+      if (opts.readOnly || opts.noClear) return;
+      await fsp.rm(r('.'), { recursive: true, force: true });
+    },
+  };
+}

package/src/runtime/server/plugins/default-storage.ts

@@ -0,0 +1,15 @@
+import { defineNitroPlugin, useStorage } from 'nitropack/runtime';
+// @ts-expect-error virtual module
+import { storageName, storagePath } from '#nuxt-filer-options';
+import fsDriver from '../drivers/fs';
+
+/**
+ * Mount the default filesystem-backed storage for nuxt-filer. We mount
+ * via a Nitro plugin rather than `nitroConfig.storage` so that our
+ * custom fs driver is bundled with the plugin and there is no runtime
+ * module resolution against the package's `dist/`.
+ */
+export default defineNitroPlugin(() => {
+  const storage = useStorage();
+  storage.mount(storageName, fsDriver({ base: storagePath }));
+});

package/src/runtime/server/utils/image.ts

@@ -0,0 +1,82 @@
+import type {
+  ImageFormat,
+  ImageTransformOptions,
+  ImageTransformResult,
+} from '../../../runtime/types';
+
+export type { ImageFormat, ImageTransformOptions, ImageTransformResult };
+
+const MIME_BY_FORMAT: Record<string, string> = {
+  webp: 'image/webp',
+  png: 'image/png',
+  jpeg: 'image/jpeg',
+  jpg: 'image/jpeg',
+  avif: 'image/avif',
+  gif: 'image/gif',
+};
+
+// `sharp` is an optional peer dependency — resolve it lazily and cache the
+// module so unrelated installs never pay for the native binary.
+type SharpModule = typeof import('sharp');
+let sharpModule: SharpModule | undefined;
+
+async function loadSharp(): Promise<SharpModule> {
+  if (sharpModule) return sharpModule;
+  try {
+    sharpModule = (await import('sharp')).default as unknown as SharpModule;
+  }
+  catch {
+    throw new Error(
+      '[nuxt-filer] Image transforms require the optional peer dependency `sharp`. Install it with `npm i sharp`.'
+    );
+  }
+  return sharpModule;
+}
+
+/**
+ * Process an image buffer with sharp: resize within a box, convert format,
+ * optimize, and (by default) preserve animation for multi-frame inputs. Used
+ * for upload-time normalization — see `useFileStorage().upload({ transform })`.
+ *
+ * Requires the optional `sharp` peer dependency; throws a clear error if it is
+ * not installed.
+ */
+export async function transformImage(
+  data: Buffer | Uint8Array,
+  options: ImageTransformOptions = {}
+): Promise<ImageTransformResult> {
+  const sharp = await loadSharp();
+
+  const animated = options.animated ?? true;
+  let pipeline = sharp(data, { animated });
+
+  if (options.width != null || options.height != null) {
+    pipeline = pipeline.resize({
+      width: options.width,
+      height: options.height,
+      fit: options.fit ?? 'inside',
+      withoutEnlargement: options.withoutEnlargement ?? true,
+      background: options.background,
+    });
+  }
+
+  if (options.format) {
+    const formatOptions
+      = options.quality != null ? { quality: options.quality } : {};
+    pipeline = pipeline.toFormat(
+      options.format as keyof import('sharp').FormatEnum,
+      formatOptions
+    );
+  }
+
+  const out = await pipeline.toBuffer({ resolveWithObject: true });
+  const format = out.info.format;
+
+  return {
+    data: out.data,
+    format,
+    mime: MIME_BY_FORMAT[format] ?? `image/${format}`,
+    width: out.info.width,
+    height: out.info.height,
+  };
+}

package/src/runtime/server/utils/storage.ts

@@ -4,10 +4,20 @@ import type {
   StoredFile,
   ExternalRef,
   FileStorageProvider,
+  ImageTransformOptions,
+  ImageTransformResult,
 } from '../../../runtime/types';
 import { useFileStorageProvider } from '../provider';
+import { transformImage } from './image';
 
-export type { FileMeta, StoredFile, ExternalRef, FileStorageProvider };
+export type {
+  FileMeta,
+  StoredFile,
+  ExternalRef,
+  FileStorageProvider,
+  ImageTransformOptions,
+  ImageTransformResult,
+};
 
 export const useFileStorage = () => {
   const provider = useFileStorageProvider();
@@ -15,9 +25,23 @@ export const useFileStorage = () => {
   async function upload(
     groupId: string,
     data: Buffer | Uint8Array,
-    options: { meta?: FileMeta } = {}
+    options: { meta?: FileMeta; transform?: ImageTransformOptions } = {}
   ): Promise<string> {
-    const { id } = await provider.create(groupId, data, options.meta);
+    let payload = data;
+
+    // Optional upload-time image processing (requires the `sharp` peer dep).
+    // The stored bytes and the metadata's mime/dimensions reflect the result.
+    if (options.transform) {
+      const result = await transformImage(data, options.transform);
+      payload = result.data;
+      if (options.meta) {
+        options.meta.mime = result.mime;
+        options.meta.width = result.width;
+        options.meta.height = result.height;
+      }
+    }
+
+    const { id } = await provider.create(groupId, payload, options.meta);
     return id;
   }
 

package/src/runtime/types.ts

@@ -8,6 +8,54 @@ export interface FileMeta {
   [key: string]: unknown;
 }
 
+/** Output image format for {@link transformImage}. */
+export type ImageFormat = 'webp' | 'png' | 'jpeg' | 'avif' | 'gif';
+
+/**
+ * Options for upload-time image processing, backed by the optional `sharp`
+ * peer dependency. Passed via `useFileStorage().upload(.., { transform })` or
+ * to the standalone `transformImage()` util.
+ */
+export interface ImageTransformOptions {
+  /** Target width in px. Combined with `fit` to bound the image. */
+  width?: number;
+  /** Target height in px. Combined with `fit` to bound the image. */
+  height?: number;
+  /**
+   * How the image is resized to fit `width`/`height`. Mirrors sharp's `fit`.
+   * Default: `'inside'` (preserve aspect ratio, fit within the box).
+   */
+  fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+  /** Never scale the image up beyond its original size. Default: `true`. */
+  withoutEnlargement?: boolean;
+  /** Output format. Default: keep the input's format. */
+  format?: ImageFormat;
+  /** Output quality (1-100) for lossy formats (webp/jpeg/avif). */
+  quality?: number;
+  /**
+   * Preserve every frame of multi-frame inputs (animated webp/gif). Default:
+   * `true`; harmless for static images. Animation is only retained when the
+   * output `format` is animation-capable (`webp`/`gif`).
+   */
+  animated?: boolean;
+  /** Background used when flattening transparency (e.g. for `contain`/jpeg). */
+  background?: string;
+}
+
+/** Result of {@link transformImage}: the processed bytes plus resolved metadata. */
+export interface ImageTransformResult {
+  /** The processed image bytes. */
+  data: Buffer;
+  /** MIME type of the processed image, e.g. `image/webp`. */
+  mime: string;
+  /** Resolved output format, e.g. `webp`. */
+  format: string;
+  /** Width of the processed image in px, if sharp could determine it. */
+  width?: number;
+  /** Height of the processed image in px, if sharp could determine it. */
+  height?: number;
+}
+
 export interface ExternalRef {
   /** External system identifier, e.g. 'jira', 'sharepoint' */
   source: string;