rehype plugin to change the `src` (and `srcset`/`sizes`) of images to optimized versions from your image CDN/optimization provider
npm install rehype-image-optimrehype plugin to change the src (and srcset/sizes) of images to optimized versions from your image CDN/optimization provider.
> [!NOTE]
> This package is still in development. APIs may change without notice.
This package is a [unified][] ([rehype][]) plugin to replace the tags in your HTML with optimized versions from your image CDN/optimization provider. It has the ability to replace the src and srcset/sizes attributes of the tag (as a bonus, it can also append the style attribute).
One of the key features of this package is how it replaces the URLs to optimized ones. Currently, it only supports Cloudflare Image Optimization's "Transform via URL", but feel free to open an issue if you want to add support for other providers. Also, you can pass in a custom transformer function when using this package.
The package will be available on npm soon.
Say we have the following HTML fragment:
``html`
…and our module example.ts looks as follows (you can use the defineOptions helper function to get type-safe options):
> [!NOTE]
> For more information, read the API section.
`typescript
import { rehype } from "rehype";
import rehypeImageOptimization, { defineOptions } from "rehype-image-optim";
const input = 
;
const result = await rehype()
.use({ settings: { fragment: true } })
.use(
rehypeImageOptimization,
defineOptions({
// use the built-in cloudflare provider
provider: "cloudflare",
// this is configured to replace the src attributesrcset
optimizeSrcOptions: {
// the options in this object is unique to the provider
options: "f=auto",
},
// this is configured to replace the attributesizes
srcsetOptionsList: [
[{}, "1x"],
[{ options: "w=200" }, "2x"],
],
// this is configured to replace the attributestyle
sizesOptionsList: ["(max-width: 600px) 100vw", "50vw"],
// this will append the attribute
style: "width: 100%",
}),
)
.process(input);
console.log(result.toString());
`
…now running node example.ts yields (formatted for readability):
`html` src="https://example.com/cdn-cgi/image/f=auto/image.jpg"
srcset="
https://example.com/cdn-cgi/image/f=auto/image.jpg 1x,
https://example.com/cdn-cgi/image/w=200/image.jpg 2x
"
sizes="(max-width: 600px) 100vw, 50vw"
style="width: 100%"
/>
Or, you can pass a function to the provider option to use a custom transformer:
`typescript
import { rehype } from "rehype";
import rehypeImageOptimization, { defineOptions } from "rehype-image-optim";
const input = 
;
const result = await rehype()
.use({ settings: { fragment: true } })
.use(
rehypeImageOptimization,
defineOptions({
provider: (originalLink, options: { a: string; b: boolean }) => {
return originalLink.replace(options.a, "replaced");
},
// As mentioned above, the type of these options is defined by the second argument of the provider function.
optimizeSrcOptions: { a: "a" },
}),
)
.process(input);
console.log(result.toString());
// 
`
The custom provider need to satisfy the following type:
`typescript`
type TransformerFunction
originalUrl: string,
options: OptOptions,
) => string;
The default export is the rehype plugin. Also, you can import the defineOptions helper function to get type-safe options (and editor hint! since this plugin has a relatively complex options structure).
The first parameter of the rehype plugin is an Options object.
Options type interface
`typescriptsrc
type Options<
Provider extends TransformerTypes | TransformerFunction
OptOptions extends OptimizeOptions
> = {
provider: Provider;
originValidation?: string | RegExp | ((arg0: string) => boolean);
/**
* Options for the image optimization. Used to replace the image property.src
*
* If set to undefined, will not replace the property.srcset
*
* Else, this value is passed to the transformer function.
*/
optimizeSrcOptions?: OptOptions;
/**
* Options for the image optimization. Used to replace the image property.descriptor
* The is a string that describes the size of the image or density.`
*
* @see https://developers.cloudflare.com/images/transform-images/make-responsive-images/
*/
srcsetOptionsList?: [OptOptions, string][];
sizesOptionsList?: string[] | string;
style?: string;
};
#### provider
Can be a string or a function.
If a string, it indicates a built-in provider. Currently, the only built-in provider is "cloudflare".
If a function, it is a custom transformer function. The function should satisfy the following type:
`typescript`
type TransformerFunction
originalUrl: string,
options: OptOptions,
) => string;
> [!NOTE]
> Notice the generic type OptOptions, which will be used to type the optimizeSrcOptions and srcsetOptionsList options below.
#### originValidation
Can be a string, a regular expression, or a function.
Usually, you don't want to optimize images from other domains. This option allows you to specify which domains are allowed to be optimized.
If a function, it should return a boolean.
#### optimizeSrcOptions
Options for replacing the src attribute. Type is OptOptions from the provider option.
#### srcsetOptionsList
Options for replacing the srcset attribute. Type is [OptOptions, string][].
The first element of the tuple is the OptOptions from the provider option, which builds the URL, and the second element is a string used as the descriptor for the URL.
You can easily find how this build the srcset attribute by the example above in Usage section.
> [!NOTE]
> If you don't know what srcset is, you can read Cloudflare's documentation or MDN's documentation.
#### sizesOptionsList
Options for replacing the sizes attribute. Type is string[] or string.
If it is a string, it will be used as the value of the sizes attribute.
If it is an array, it will be joined with a comma.
#### style
Type is string.
Appends the style attribute to the tag.
Transform via URL | Cloudflare Image Optimization docs
OptOptions
type interface
`typescriptsrc
{
/**
* Options for the image optimization. Used to replace the image property.string
*
* Can be or string[]. If an array is provided, it is joined with a comma.`
*
* The following examples are equivalent:
* @example "f=auto,w=320,q=80"
* @example ["f=auto", "w=320", "q=80"]
* @example ["f=auto,w=320", "q=80"]
*
* @see https://developers.cloudflare.com/images/transform-images/transform-via-url/#options
*/
options?: OptimizeOptions;
resultOrigin?: string;
}
More documentation is coming soon. For now, you can read the tests for examples. link-transformer.test.ts
If you find a bug or want to add a new provider, please open an issue or a pull request.
As to add a new provider, you can create a new file in the lib/link-transformer directory, and edit the /lib/link-transformer/index.ts file to export the new provider. Please add tests for the new provider in the test/link-transformer.test.ts` file if possible.
[unified]: https://github.com/unifiedjs/unified
[rehype]: https://github.com/rehypejs/rehype