files-sdk-superfiles

files-sdk adapter for SuperFiles — programmable object storage with a Cloudinary-compatible on-the-fly image CDN.

Install

npm install files-sdk-superfiles
# files-sdk is optional — only needed if you use the adapter
npm install files-sdk

Quick start

Standalone URL utilities (no files-sdk needed)

import { buildUrl, buildSrcSet } from "files-sdk-superfiles";

// Basic CDN URL
buildUrl("https://files.montr.online", "media", "photos/hero.jpg")
// → "https://files.montr.online/cdn/media/photos/hero.jpg"

// With transforms — params are sorted alphabetically for cache consistency
buildUrl("https://files.montr.online", "media", "photos/hero.jpg", { w: 800, f: "auto", q: 80 })
// → "https://files.montr.online/cdn/media/f_auto,q_80,w_800/photos/hero.jpg"

// Responsive srcset
buildSrcSet("https://files.montr.online", "media", "hero.jpg", [400, 800, 1200], { f: "auto" })
// → "https://…/cdn/media/f_auto,w_400/hero.jpg 400w, …/f_auto,w_800/hero.jpg 800w, …"

files-sdk adapter

import { Files } from "files-sdk";
import { superfiles } from "files-sdk-superfiles";

const files = new Files({
  adapter: superfiles({
    url: "https://files.montr.online",
    token: "sf_live_...",
    bucket: "media",
  }),
});

// Standard files-sdk methods
await files.upload("photos/hero.jpg", readStream);
await files.download("photos/hero.jpg");
files.url("photos/hero.jpg");
// → "https://files.montr.online/cdn/media/photos/hero.jpg"

// Transform URL via raw escape hatch
import type { SuperFilesRawClient } from "files-sdk-superfiles";
const sf = files.raw as SuperFilesRawClient;
sf.transformUrl("photos/hero.jpg", { w: 800, f: "auto" });
// → "https://files.montr.online/cdn/media/f_auto,w_800/photos/hero.jpg"

const signed = await sf.signedUpload("uploads/hero.jpg", { contentType: "image/jpeg" });
// { signedUrl, expiresAt, method: "PUT", headers: { "Content-Type": "image/jpeg" } }

All JSON responses are runtime-validated with the same @superfiles/types Zod contracts used by the API and OpenAPI specification. A malformed successful response throws instead of returning partially undefined data.

Transform parameters

| Param | Type | Default | Description | |---|---|---|---| | w | number (1–8000) | original | Output width in pixels | | h | number (1–8000) | original | Output height in pixels | | c | contain·cover·fill·crop | contain | Crop/fit mode when both w and h are set | | ar | string e.g. "16:9" | — | Derives missing dimension from aspect ratio | | f | jpg·png·webp·avif·gif·auto | original | Output format. auto = best format from Accept header | | q | number (1–100) | 85 | Quality for lossy formats (JPEG, WebP, AVIF) | | t | number (seconds) | 0 | Video frame timestamp (thumbnail extraction) |

Next.js image loader

// superfiles-loader.ts (in your project root)
import superFilesLoader from "files-sdk-superfiles/next";
export default superFilesLoader;

// next.config.js
module.exports = { images: { loaderFile: "./superfiles-loader.ts" } }

// Usage in JSX — width and quality are forwarded as w and q transforms
<Image src="products/hero.jpg" width={800} height={600} alt="Hero" />
// → https://files.montr.online/cdn/media/f_auto,q_85,w_800/products/hero.jpg

Required env vars:

NEXT_PUBLIC_SUPERFILES_URL=https://files.montr.online
NEXT_PUBLIC_SUPERFILES_BUCKET=media

React hook

import { useImageUrl, useSrcSet } from "files-sdk-superfiles/react";

const src = useImageUrl("products/hero.jpg", { w: 800, f: "auto" });
// → "https://files.montr.online/cdn/media/f_auto,w_800/products/hero.jpg"

const srcSet = useSrcSet("hero.jpg", [400, 800, 1200], { f: "auto" });
// → "…/f_auto,w_400/hero.jpg 400w, …/f_auto,w_800/hero.jpg 800w, …"

Pass opts.baseUrl / opts.bucket to override env vars in multi-bucket apps:

const src = useImageUrl("avatar.jpg", { w: 64 }, { bucket: "avatars" });

Exports

files-sdk-superfiles          → buildUrl, buildSrcSet, normaliseTransform, superfiles adapter
                                 SuperFilesTransformOptions, SuperFilesRawClient types
files-sdk-superfiles/next     → superFilesLoader (default export), SuperFilesImageLoaderProps
files-sdk-superfiles/react    → useImageUrl, useSrcSet

files.signedUploadUrl() follows the files-sdk v2 contract and returns { method, url, headers? }. Use files.raw.signedUpload() when you also need Superfiles-specific expiry metadata.

License

MIT