rehype image optim (WIP)

rehype 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.

What is this?

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.

Install

The package will be available on npm soon.

Usage

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 attribute
optimizeSrcOptions: {
// the options in this object is unique to the provider
options: "f=auto",
},
// this is configured to replace the srcset attribute
srcsetOptionsList: [
[{}, "1x"],
[{ options: "w=200" }, "2x"],
],
// this is configured to replace the sizes attribute
sizesOptionsList: ["(max-width: 600px) 100vw", "50vw"],
// this will append the style 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;
`

API

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).

$3

The first parameter of the rehype plugin is an Options object.

#### 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.

Built-in providers

$3

Transform via URL | Cloudflare Image Optimization docs

More documentation is coming soon. For now, you can read the tests for examples. link-transformer.test.ts

Contributing

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