plugin-react-static-images-cp v0.1.1

Based on https://github.com/dev-rsilver/plugin-react-static-images

Image Plugin for React Static

An image plugin for React Static that makes it easy to transform images, provide them to a route, and utilize them in static pages. The plugin supports lazy loaded images, placeholders, and responsive loading.

Using the Plugin

To use the plugin: 1. Add the plugin to React Static in static.config.js 2. Import {Images} from 'plugin-react-static-images' in static.config.js and use let myImage = await Images.get(sources, transformName, options) to ingest images and apply transformations 3. Pass the returned images to your route as you would any other data 4. Import {ImageComponent} from 'plugin-react-static-images/components' in your page and use it in your JSX: <ImageComponent img={myImage} />

Additional detail for each step follows.

Adding the Plugin

Add the plugin to React Static's plugins like so:

plugins: [
   ...other plugins...npm install -g @jsdevtools/npm-publishnpm install -g @jsdevtools/npm-publish
   'plugin-react-static-images'
]

Retrieving and Transforming Images

In static.config.js, import the images object:

import {Images} from 'plugin-react-static-images'

Then, use the Images.get function to retrieve images and apply transformations. The function has this signature:

await Images.get(sources, transformName, options)

Sources

Sources is either a single object, or an array of objects, consisting of the following objects:

{type: "folder", value: pathString}

{type: "file", value: pathString}

{type: "url", value: urlString}

If you supply a single source, then Images.get will return a single image. If you supply an array of sources, then Images.get will return an array of images. If your source is a folder, all images (.jpg, .jpeg, .png, .bmp, .tiff) that are located in the folder will be ingested.

TransformName

For transformName, there is an available default transform available called "builtin" that supports a wide range of transformation options. If desired, you can also create your own custom transform and use it.

To use the default transform, supply "builtin"

Options

For the options object, you can provide the following options if you use the "builtin" transform:

Example 1

The returned image will use a placeholder but the image will also load immediately and the placeholder will be replaced shortly after the page loads. A single image is returned.

let image = await Images.get({ type: "file", value: "./images/image1.jpg" }, "builtin", { usePlaceholder: true })

Example 2

Placeholders will be utilized but images will load lazily. That is, image placeholders will be displayed and, as those placeholders enter the viewport, they will be replaced with the target images. An array of images is returned.

let images = await Images.get({ type: "folder", value: "./images/"}, "builtin", { usePlaceholder: true, load: "lazy" })

Example 3

Both a file and a folder are ingested and no transform is utilized. In this case, images will be ingested but no transformations applied. However, images will still be returned from the function call, which allows you to pass them to your route.

let images = await Images.get([{ type: "file", value: "./images/folder1/image1.png" }, { type: "folder", value: "./images/"})

Example 4

Placeholders will be generated and images will load responsively. So, if your image is set to 90%, as the image scales up, the underlying image src will be updated with a higher resolution image if available.

let images = await Images.get({ type: "folder", value: "./images/" }, "builtin", { usePlaceholder: true, useResponsive: true })

Performance Considerations

The plugin does not make assumptions about image quality, size, or other factors. When ingesting images, you may want to set the quality and maxDimension options as these options can significantly impact the size of your images. Additionally, the useResponsive option provides dynamically chosen image sizes at the cost of longer build times since additional images have to be created.

Sending Images to Route

Sending your images to your route works like sending other data. In static.config.js:

let myImage = await Images.get({ type: "file", path: "your_path" }, "builtin", { usePlaceholder: true })

return [{
   path: '/blog',
   getData: () => ({
     posts,
     myImage 
   })
}]

Using Images in Your Page

In the page for your route, assign your images to variables via useRouteData as usual:

const {posts, myImage} = useRouteData()

Import the ImageComponent:

import {ImageComponent} from 'plugin-react-static-images/components'

Use the ImageComponent component in your JSX. For example:

return(<div>
  <ImageComponent img={myImage} style={{width:500}} />
</div>)

If you have an array of images and want to access a single image:

return(<div>
  <ImageComponent img={myImages[0]} />
</div>)

An array of images is a standard array, and an ImageComponent is a standard React component, so you could easily create an array of image components for use in your page:

let imageComponents = []
myImages.forEach((value, i) => { imageComponents.push(<ImageComponent key={i} img={value} />) }

The <ImageComponent> is wrapper around an underlying standard <img> element. All props that aren't related to the ImageComponent are passed to the underlying <img> element.

Responsive Image Considerations

Each image that utilizes the responsive image feature has multiple images created at different sizes. Depending on how you intend to display an image, the fact that there are different sized images may have unexpected results. For instance, using a regular img element, if you're starting with a very large image and you set a maxWidth that's a percentage, and a maxHeight that's a pixel value, you might expect that the image will automatically fill the height that you've specified. With responsive images, however, the maximum size of the image that's displayed at runtime may not be large enough to achieve a full fill of the component, so you would need to additionally set a minHeight to achieve a similar result.

Creating a Custom Transform

The builtin transform should be sufficient for many use cases. In combination with Images.get, your static site can ingest numerous images and apply transformations to them. You can also utilize multiple Images.get operations in your static.config.js file to apply different transformations to different sets of images.

You might find a use case for which you want to create your own transform, however.

To do so, simply create a new file and export a default function like so:

module.exports.default = ({image, options}) => {
}

The function will receive a TransformableImage object, and the options passed to Images.get.

The TransformableImage object provides the following operations:

Your custom transform must return an object:

return {
   image: TransformableImage object
   placeholder: TransformableImage object (optional)
   responsive: array of TransformableImage objects (optional)
   load: "immediate" or "lazy" (optional)
}

Next, simply pass an option to the plugin in static.config.js like so:

plugins: [
  [
    'plugin-react-static-images',
    {
      transforms: [
        { name: "yourTransformName", location: path.resolve("your_transform_path") }
      ]
    }
  ]
]

Then, instead of referencing builtin in Images.get, you can reference the name of your transformation.

Plugin Options

You can pass an option, 'maxAssetSize', to the plugin to determine whether images are base64 encoded and sent via route data, or accessed via a url. Up to and including maxAssetSize, images will be base64 encoded. Above maxAssetSize, images will be referenced via url. The default is 100000.

plugins: [
  [
    'plugin-react-static-images',
    {
      maxAssetSize: 50000
    }
  ]
]