nuxt-filer 0.0.4 → 0.0.5

package/README.md

@@ -15,6 +15,7 @@ File storage module for Nuxt. Provides a server-side `useFileStorage()` composab
 - **Zero-config default** — works out of the box with local filesystem storage, no database required
 - **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
 
 ## Quick Setup
 
@@ -96,6 +97,39 @@ export default defineEventHandler(async (event) => {
 | `external?.push(groupId, id, data, meta)` | Push to external system |
 | `external?.pull(groupId, ref)` | Pull from external system |
 
+## `@nuxt/image` Integration
+
+If `@nuxt/image` is installed alongside `nuxt-filer`, the module automatically registers a `filer` image provider and an IPX endpoint that pulls bytes from your storage provider, runs them through Sharp, and returns the result.
+
+```vue
+<template>
+  <NuxtImg
+    provider="filer"
+    :src="`${groupId}/${fileId}`"
+    width="200"
+    height="200"
+    fit="cover"
+    format="webp"
+  />
+</template>
+```
+
+Generated URLs look like `/_filer-ipx/w_200,h_200,fit_cover,format_webp/<groupId>/<fileId>` and are served with `cache-control: max-age=...`, `last-modified`, and `etag` for `if-modified-since` / `if-none-match` revalidation.
+
+The integration can be configured or turned off:
+
+```ts
+filer: {
+  image: {
+    enabled: true,            // false to disable; 'force' to register without @nuxt/image
+    route: '/_filer-ipx',     // base path for the IPX endpoint
+    providerName: 'filer',    // name used in <NuxtImg provider="..." />
+  },
+},
+```
+
+`@nuxt/image` and `ipx` are declared as optional peer dependencies — they only need to be installed if you want to use this integration.
+
 ## Custom Provider
 
 For advanced use cases (database-backed metadata, S3 storage, external file sync), implement the `FileStorageProvider` interface and register it in a Nitro plugin:

package/dist/module.d.mts

@@ -1,5 +1,18 @@
 import * as _nuxt_schema from '@nuxt/schema';
 
+interface FilerImageOptions {
+    /**
+     * Enable the @nuxt/image provider + IPX route. When `true` (the default),
+     * the integration registers only if `@nuxt/image` is also installed; when
+     * `false`, it is never registered. Set to `'force'` to register the routes
+     * even when `@nuxt/image` cannot be detected (mainly useful for tests).
+     */
+    enabled?: boolean | 'force';
+    /** Base path for the IPX endpoint. Default: `/_filer-ipx`. */
+    route?: string;
+    /** Name to register the @nuxt/image provider under. Default: `filer`. */
+    providerName?: string;
+}
 interface ModuleOptions {
     /** Nitro storage mount name for binary file data. Default: 'documents' */
     storageName?: string;
@@ -7,8 +20,10 @@ interface ModuleOptions {
     storagePath?: string;
     /** Provider mode. 'unstorage' uses the built-in unstorage provider. 'custom' expects you to call setFileStorageProvider() in a Nitro plugin. Default: 'unstorage' */
     provider?: 'unstorage' | 'custom';
+    /** @nuxt/image integration. Set to `false` to disable, or pass an object to override defaults. */
+    image?: boolean | FilerImageOptions;
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
 export { _default as default };
-export type { ModuleOptions };
+export type { FilerImageOptions, ModuleOptions };

package/dist/module.json

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

package/dist/module.mjs

@@ -1,4 +1,4 @@
-import { defineNuxtModule, createResolver, addServerImports, addImports } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, addServerImports, addImports, hasNuxtModule, addServerHandler } from '@nuxt/kit';
 import { consola } from 'consola';
 
 const module = defineNuxtModule({
@@ -9,7 +9,8 @@ const module = defineNuxtModule({
   defaults: {
     storageName: "documents",
     storagePath: ".data/documents",
-    provider: "unstorage"
+    provider: "unstorage",
+    image: true
   },
   setup(options, nuxt) {
     const resolver = createResolver(import.meta.url);
@@ -42,9 +43,34 @@ const module = defineNuxtModule({
         type: true
       }
     ]);
+    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) {
+      addServerHandler({
+        route: `${ipxRoute}/**`,
+        handler: resolver.resolve("./runtime/server/handlers/ipx")
+      });
+      const imageConfig = nuxt.options.image ?? {};
+      const providers = imageConfig.providers ?? {};
+      providers[providerName] = {
+        name: providerName,
+        provider: resolver.resolve("./runtime/image/provider"),
+        options: { baseURL: ipxRoute }
+      };
+      imageConfig.providers = providers;
+      nuxt.options.image = imageConfig;
+    } else if (imageEnabled && options.image !== false) {
+      consola.info(
+        "nuxt-filer: @nuxt/image not detected \u2014 IPX integration disabled. Install `@nuxt/image` to enable optimized image variants."
+      );
+    }
     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-image"] = `export const ipxRoute = ${JSON.stringify(ipxRoute)}`;
       if (options.provider === "unstorage") {
         nitroConfig.storage = nitroConfig.storage || {};
         nitroConfig.storage[options.storageName] = {

package/dist/runtime/image/provider.d.ts

@@ -0,0 +1,7 @@
+import type { ProviderGetImage } from '@nuxt/image';
+interface FilerProviderOptions {
+    baseURL?: string;
+}
+export declare const getImage: ProviderGetImage;
+export declare const validateDomains = false;
+export type { FilerProviderOptions };

package/dist/runtime/image/provider.js

@@ -0,0 +1,17 @@
+const operationsGenerator = (modifiers) => {
+  const ops = [];
+  for (const [key, value] of Object.entries(modifiers)) {
+    if (value === void 0 || value === null || value === "" || value === false) continue;
+    ops.push(`${key}_${value}`);
+  }
+  return ops.length ? ops.join(",") : "_";
+};
+export const getImage = (src, { modifiers = {}, baseURL } = {}) => {
+  const root = (baseURL ?? "/_filer-ipx").replace(/\/+$/, "");
+  const ops = operationsGenerator(
+    modifiers
+  );
+  const path = src.replace(/^\/+/, "");
+  return { url: `${root}/${ops}/${path}` };
+};
+export const validateDomains = false;

package/dist/runtime/server/handlers/ipx.d.ts

@@ -0,0 +1,6 @@
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<string | void | Buffer<ArrayBufferLike> | {
+    error: {
+        message: string;
+    };
+}>>;
+export default _default;

package/dist/runtime/server/handlers/ipx.js

@@ -0,0 +1,49 @@
+import { defineEventHandler } from "h3";
+import { createIPX, createIPXH3Handler } from "ipx";
+import { ipxRoute } from "#nuxt-filer-image";
+import { useFileStorageProvider } from "../provider.js";
+function parseId(id) {
+  const lastSlash = id.lastIndexOf("/");
+  if (lastSlash <= 0 || lastSlash === id.length - 1) return null;
+  return [id.slice(0, lastSlash), id.slice(lastSlash + 1)];
+}
+const filerStorage = {
+  name: "nuxt-filer",
+  async getMeta(id) {
+    const parsed = parseId(id);
+    if (!parsed) return void 0;
+    const [groupId, fileId] = parsed;
+    const provider = useFileStorageProvider();
+    const file = await provider.get(groupId, fileId);
+    if (!file) return void 0;
+    const mtime = file.updatedAt ?? file.createdAt ?? /* @__PURE__ */ new Date();
+    return {
+      mtime,
+      maxAge: 60 * 60 * 24 * 365
+    };
+  },
+  async getData(id) {
+    const parsed = parseId(id);
+    if (!parsed) return void 0;
+    const [groupId, fileId] = parsed;
+    const data = await useFileStorageProvider().getData(groupId, fileId);
+    if (!data) return void 0;
+    return data;
+  }
+};
+let _handler = null;
+let _ipx = null;
+function getHandler() {
+  if (!_handler) {
+    _ipx = createIPX({ storage: filerStorage });
+    _handler = createIPXH3Handler(_ipx);
+  }
+  return _handler;
+}
+export default defineEventHandler((event) => {
+  const original = event.path;
+  let sub = original.startsWith(ipxRoute) ? original.slice(ipxRoute.length) : original;
+  if (!sub.startsWith("/")) sub = `/${sub}`;
+  event.path = sub;
+  return getHandler()(event);
+});

package/dist/types.d.mts

@@ -1,3 +1,3 @@
 export { default } from './module.mjs'
 
-export { type ModuleOptions } from './module.mjs'
+export { type FilerImageOptions, type ModuleOptions } from './module.mjs'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-filer",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "File storage module for Nuxt",
   "repository": {
     "type": "git",
@@ -55,17 +55,31 @@
   "devDependencies": {
     "@nuxt/devtools": "^3.2.4",
     "@nuxt/eslint-config": "^1.15.2",
+    "@nuxt/image": "^2.0.0",
     "@nuxt/module-builder": "^1.0.2",
     "@nuxt/schema": "^4.4.2",
     "@nuxt/test-utils": "^4.0.0",
     "@types/node": "latest",
     "changelogen": "^0.6.2",
     "eslint": "^10.1.0",
+    "ipx": "^3.1.1",
     "nuxt": "^4.4.2",
     "typescript": "~6.0.2",
     "vitest": "^4.1.2",
     "vue-tsc": "^3.2.6"
   },
+  "peerDependencies": {
+    "@nuxt/image": "^2.0.0",
+    "ipx": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@nuxt/image": {
+      "optional": true
+    },
+    "ipx": {
+      "optional": true
+    }
+  },
   "packageManager": "pnpm@10.33.0",
   "pnpm": {
     "onlyBuiltDependencies": [

package/src/runtime/image/provider.ts

@@ -0,0 +1,33 @@
+import type { ProviderGetImage } from '@nuxt/image';
+
+interface FilerProviderOptions {
+  baseURL?: string;
+}
+
+const operationsGenerator = (
+  modifiers: Record<string, string | number | boolean | undefined>
+): string => {
+  const ops: string[] = [];
+  for (const [key, value] of Object.entries(modifiers)) {
+    if (value === undefined || value === null || value === '' || value === false) continue;
+    ops.push(`${key}_${value}`);
+  }
+  return ops.length ? ops.join(',') : '_';
+};
+
+export const getImage: ProviderGetImage = (
+  src: string,
+  { modifiers = {}, baseURL }: { modifiers?: Record<string, unknown>; baseURL?: string } = {},
+  // ctx is provided by @nuxt/image but unused here
+) => {
+  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}` };
+};
+
+export const validateDomains = false;
+
+export type { FilerProviderOptions };

package/src/runtime/server/handlers/ipx.ts

@@ -0,0 +1,64 @@
+import { defineEventHandler } from 'h3';
+import { createIPX, createIPXH3Handler, type IPX, type IPXStorage } from 'ipx';
+// @ts-expect-error virtual module injected by the module
+import { ipxRoute } from '#nuxt-filer-image';
+import { useFileStorageProvider } from '../provider';
+
+/**
+ * Maps an IPX `id` (the path after the modifiers segment) to a `(groupId, fileId)`
+ * pair as used by the file storage provider. Ids are expected as
+ * `groupId/fileId` — additional `/` characters in the group id are preserved.
+ */
+function parseId(id: string): [string, string] | null {
+  const lastSlash = id.lastIndexOf('/');
+  if (lastSlash <= 0 || lastSlash === id.length - 1) return null;
+  return [id.slice(0, lastSlash), id.slice(lastSlash + 1)];
+}
+
+const filerStorage: IPXStorage = {
+  name: 'nuxt-filer',
+  async getMeta(id) {
+    const parsed = parseId(id);
+    if (!parsed) return undefined;
+    const [groupId, fileId] = parsed;
+    const provider = useFileStorageProvider();
+    const file = await provider.get(groupId, fileId);
+    if (!file) return undefined;
+    const mtime = file.updatedAt ?? file.createdAt ?? new Date();
+    return {
+      mtime,
+      maxAge: 60 * 60 * 24 * 365,
+    };
+  },
+  async getData(id) {
+    const parsed = parseId(id);
+    if (!parsed) return undefined;
+    const [groupId, fileId] = parsed;
+    const data = await useFileStorageProvider().getData(groupId, fileId);
+    if (!data) return undefined;
+    // IPX accepts ArrayBuffer | Buffer; pass the buffer view directly.
+    return data as unknown as ArrayBuffer;
+  },
+};
+
+let _handler: ReturnType<typeof createIPXH3Handler> | null = null;
+let _ipx: IPX | null = null;
+function getHandler() {
+  if (!_handler) {
+    _ipx = createIPX({ storage: filerStorage });
+    _handler = createIPXH3Handler(_ipx);
+  }
+  return _handler;
+}
+
+export default defineEventHandler((event) => {
+  // Strip the configured base prefix so IPX sees the URL it expects:
+  // `/<modifiers>/<groupId>/<fileId>`.
+  const original = event.path;
+  let sub = original.startsWith(ipxRoute)
+    ? original.slice((ipxRoute as string).length)
+    : original;
+  if (!sub.startsWith('/')) sub = `/${sub}`;
+  event.path = sub;
+  return getHandler()(event);
+});