Skip to main content


Create a new resource route that imports the imageLoader function and exports as loader. By default, the image component uses the route "/api/image", but any route can be used.

import type { LoaderFunction } from "remix";
import { imageLoader, DiskCache } from "remix-image/server";

const config = {
selfUrl: "http://localhost:3000",
cache: new DiskCache(),

export const loader: LoaderFunction = ({ request }) => {
return imageLoader(config, request);


selfUrlstringYesThe URL of the local server.
resolverResolverfetchResolverThe image resolver to use.
transformerTransformer or nullpureTransformerA transformer function that handles mutations of images. If this option is null, transformation will be skipped.
useFallbackFormatbooleantrueIf RemixImage should fallback to the fallback mime type if the output type is not supported.
fallbackFormatMimeTypeMimeType.PNGThe output mime type the image should fallback to if the provided type is not supported.
useFallbackTransformerbooleantrueIf RemixImage should fallback to the default transformer if custom transformer fails.
fallbackTransformerTransformerpureTransformerThe transformer the loader should use if the provided custom transformer fails.
cacheCacheThe configuration for the local image cache. Setting this to null will disable the cache.
defaultOptionsPartial<SizelessOptions>Default TransformOptions to use, can be overridden by the client.
redirectOnFailbooleanfalseRedirect image to original source if RemixImage fails.
skipFormatsSet<MimeType> or nullSet([MimeType.SVG])A set of mime types that should be returned without transformation.
basePathstring"public"The base file path used for the resolver.
whitelistedDomainsstring[] or nullnullAn array of domains that assets can be fetched from. Set to null to disable.
blacklistedDomainsstring[] or nullnullAn array of domains that assets are not allowed to be fetched from. Only used if whitelistedDomains is not null.
verbosebooleanfalseEnables verbose logging for debugging

Cache Types

DiskCacheA cache that stores images in memory and on disk (depending on size) for the best efficiency. To use, install the @next-boost/hybrid-disk-cache library from npm.{ path: string, ttl: number, tbd: number }
MemoryCacheA cache that only stores images in memory. Designed for platforms that do not have native disk access like Cloudflare.{ maxSize: number (bytes), ttl: number, tbd: number }

Note: Due to Remix request purging, MemoryCache will clear itself automatically on each request in development. This will not occur during production, and it will perform as expected.

Transformer Types

pureTransformerThe default image transformer, supports all platforms at the cost of performance.
sharpA faster image transformer that uses the file-system, offers the best performance. To use, take a look at these docs.

Note: By default, Remix-Image uses pureTransformer, which supports image transformations for the following types: JPEG, PNG, GIF (non-animated), BMP, and TIFF. If you would like to use additional file types, you must use a custom transformer.

Resolver Types

fetchResolverThe default image resolver, fetches images over the network.
fsResolverAn image resolver that retrieves local images from the file-system.
kvResolverA resolver for assets stored in Workers KV (for retrieving local images on Remix projects hosted on Cloudflare Workers.) To use, install the @cloudflare/kv-asset-handler library from npm.

You can create a custom resolver by combining resolvers and passing this to the loader options:

import {
} from "remix-image/server";

export const myResolver: Resolver = async (asset, url, options, basePath) => {
if (asset.startsWith("/") && (asset.length === 1 || asset[1] !== "/")) {
return fsResolver(asset, url, options, basePath);
} else {
return fetchResolver(asset, url, options, basePath);

const config = {
selfUrl: "http://localhost:3000",
cache: new MemoryCache(),
resolver: myResolver,

export const loader: LoaderFunction = ({ request }) => {
return imageLoader(config, request);

Cloudflare / Platforms Without File-System Access

Some platforms like Cloudflare Workers do not support file-systems and Node packages. In this case, several options need to be provided to the loader config, so take a look at these docs.