Skip to content

Commit

Permalink
Merge pull request #42 from Josh-McFarlin/client-loaders
Browse files Browse the repository at this point in the history 
feat(package): added Client Loader functions
  • Loading branch information
@Josh-McFarlin
Josh-McFarlin authored Jul 1, 2022
2 parents c086ed4 + 6d49d22 commit d87cc1d
Show file tree
Hide file tree
Showing 21 changed files with 497 additions and 49 deletions.
84 changes: 84 additions & 0 deletions docs/docs/client-loader.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
---
sidebar_position: 8
---

# ClientLoader

Client Loader Functions are used to construct the URL for the `Image` and `BaseImage` components and the `useResponsiveImage` hook.

Using `remixImageLoader` enables Remix-Image’s advanced transformation options, which includes transformation caching and image operations such as `resize`, `crop`, `rotate`, `blur`, and `flip`.

However, using alternative (and likely paid) services and their client loaders may result in faster response times, as the Remix server will not be slowed down by requests for new image transformations.

We suggest trying the default `remixImageLoader` function to see if it works for your apps, and then upgrade to a paid alternative if needed. Only websites with high traffic and/or many dynamic image assets will need an alternative client loader.

## Supported Loaders

### Remix Image Loader

`remixImageLoader` is the default loader used by Remix-Image. In most cases you will want to use this loader.

### Cloudflare Images Loader

`cloudflareImagesLoader` is a loader used to transform images using the paid [Cloudflare Images](https://developers.cloudflare.com/images/) service.

### Cloudinary Loader

`cloudinaryLoader` is a loader used to transform images using the paid [Cloudinary](https://cloudinary.com/) service.

**Note**: Remember to set `loaderUrl` to your API url! This should be a string similar to `https://res.cloudinary.com/<cloud_name>/`

### Imgix Loader

`imgixLoader` is a loader used to transform images using the paid [Imgix](https://imgix.com/) service.

**Note**: Remember to set `loaderUrl` to your API url! This should be a string similar to `https://<subdomain>.imgix.net/`

## Usage

### `BaseImage` and `Image` Components

```typescript jsx
import { Image, remixImageLoader, cloudflareImagesLoader, cloudinaryLoader, imgixLoader } from "remix-image";

<Image
loaderUrl="/api/image" // Required when using cloudinaryLoader or imgixLoader
loader={remixImageLoader or cloudflareImagesLoader or cloudinaryLoader or imgixLoader}
src="..."
width="..."
height="..."
alt="..."
responsive={[
{
size: {
width: 100,
height: 100,
},
maxWidth: 200,
},
]}
/>
```

### `useResponsiveImage` Hook

```typescript jsx
import { useResponsiveImage, remixImageLoader, cloudflareImagesLoader, cloudinaryLoader, imgixLoader } from "remix-image";

const Image: React.FC<ImageProps> = ({
className,
loaderUrl = "/api/image", // Required when using cloudinaryLoader or imgixLoader
responsive = [],
...imgProps
}) => {
const responsiveProps = useResponsiveImage(imgProps, responsive, [1], loaderUrl, remixImageLoader or cloudflareImagesLoader or cloudinaryLoader or imgixLoader);

return (
<img
className={clsx(classes.root, className)}
{...imgProps}
{...responsiveProps}
/>
);
};
```
46 changes: 27 additions & 19 deletions docs/docs/component.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,11 @@ Use `Image` element if you would like to use the performance optimizations built
Import the `Image` component and specify the url to the resource route used by the `imageLoader` function.

```typescript jsx
import { Image } from "remix-image";
import { Image, remixImageLoader } from "remix-image";

<Image
loaderUrl="/api/image"
loader={remixImageLoader}
src="..."
width="..."
height="..."
Expand All @@ -40,17 +41,21 @@ import { Image } from "remix-image";
```

## PropTypes
| Name | Type | Required | Default | Description |
|:----------------------:|:------------------------------------------------------------------:|:--------:|:--------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
| loaderUrl | string | | `"/api/image"` | The path of the image loader resource route. The `loaderUrl` prop is optional if the resource route has been created at the path `"/api/image"`. |
| responsive | { size: { width: number; height: number; }; maxWidth?: number; }[] | | `[]` | An array of responsive sizes. The resource route is not called if this prop is not provided. |
| options | TransformOptions | | `{}` | TransformOptions that can be used to override the defaults provided to the loader. |
| dprVariants | number or number[] | | `[1]` | Different DPR variants to generate images for. This value will always be merged into an array with value [1]. |
| unoptimized | boolean | | `false` | Set this prop to `true` to disable all image optimizations, which is equivalent to using the `BaseImage` component. |
| placeholder | "blur" or "empty" | | `"empty"` | The type of placeholder to show before the image has loaded. `"blur"` displays a scaled and blurred 15px image, while `"empty"` shows nothing. |
| blurDataURL | string or null | | `null` | The small image to show when `placeholder` is `"blur"`, which can be a URL or Base64 image. If this prop is not set or set to `null` it will automatically generate a small image using the image loader. |
| placeholderAspectRatio | number or null | | `null` | The aspect ratio to use for the placeholder before the full size image loads. If `null`, Remix-Image will try to predict this value using the `responsive` prop. |
| onLoadingComplete | OnLoadingComplete or null | | `null` | A callback function that receives the dimensions of the full-sized image once it has loaded. |
| Name | Type | Required | Default | Description |
|:----------------------:|:------------------------------------------------------------------:|:--------------------------------------------------------------------:|:-------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
| loaderUrl | string | Yes when using `cloudinaryLoader` or `imgixLoader` for `loader` prop | `"/api/image"` | The path of the image loader resource route. The `loaderUrl` prop is optional if the resource route has been created at the path `"/api/image"`. |
| loader | ClientLoader | | `remixImageLoader` | The ClientLoader to use for generating the transformed image. |
| responsive | { size: { width: number; height: number; }; maxWidth?: number; }[] | | `[]` | An array of responsive sizes. The resource route is not called if this prop is not provided. |
| options | TransformOptions | | `{}` | TransformOptions that can be used to override the defaults provided to the loader. |
| dprVariants | number or number[] | | `[1]` | Different DPR variants to generate images for. This value will always be merged into an array with value [1]. |
| unoptimized | boolean | | `false` | Set this prop to `true` to disable all image optimizations, which is equivalent to using the `BaseImage` component. |
| placeholder | "blur" or "empty" | | `"empty"` | The type of placeholder to show before the image has loaded. `"blur"` displays a scaled and blurred 15px image, while `"empty"` shows nothing. |
| blurDataURL | string or null | | `null` | The small image to show when `placeholder` is `"blur"`, which can be a URL or Base64 image. If this prop is not set or set to `null` it will automatically generate a small image using the image loader. |
| placeholderAspectRatio | number or null | | `null` | The aspect ratio to use for the placeholder before the full size image loads. If `null`, Remix-Image will try to predict this value using the `responsive` prop. |
| onLoadingComplete | OnLoadingComplete or null | | `null` | A callback function that receives the dimensions of the full-sized image once it has loaded. |

### ClientLoader Options
By default, `remixImageLoader` is used. If you would like to use an external ClientLoader, please refer to the [ClientLoader documentation](./client-loader.md).

**Note**: The `Image` component extends the native `img` element, so any props used with `img` can be provided to the `Image` component.

Expand Down Expand Up @@ -82,18 +87,21 @@ import { BaseImage } from "remix-image";
```

## PropTypes
| Name | Type | Required | Default | Description |
|:-----------:|:------------------------------------------------------------------:|:--------:|:------------:|:------------------------------------------------------------------------------------------------------------------------------------------------:|
| loaderUrl | string | | "/api/image" | The path of the image loader resource route. The `loaderUrl` prop is optional if the resource route has been created at the path `"/api/image"`. |
| responsive | { size: { width: number; height: number; }; maxWidth?: number; }[] | | [] | An array of responsive sizes. The resource route is not called if this prop is not provided. |
| options | TransformOptions | | {} | TransformOptions that can be used to override the defaults provided to the loader. |
| dprVariants | number or number[] | | [1] | Different DPR variants to generate images for. This value will always be merged into an array with value [1]. |
| Name | Type | Required | Default | Description |
|:-----------:|:------------------------------------------------------------------:|:--------------------------------------------------------------------:|:-------------------:|:------------------------------------------------------------------------------------------------------------------------------------------------:|
| loaderUrl | string | Yes when using `cloudinaryLoader` or `imgixLoader` for `loader` prop | `"/api/image"` | The path of the image loader resource route. The `loaderUrl` prop is optional if the resource route has been created at the path `"/api/image"`. |
| loader | ClientLoader | | `remixImageLoader` | The ClientLoader to use for generating the transformed image. |
| responsive | { size: { width: number; height: number; }; maxWidth?: number; }[] | | `[]` | An array of responsive sizes. The resource route is not called if this prop is not provided. |
| options | TransformOptions | | `{}` | TransformOptions that can be used to override the defaults provided to the loader. |
| dprVariants | number or number[] | | `[1]` | Different DPR variants to generate images for. This value will always be merged into an array with value [1]. |

### ClientLoader Options
By default, `remixImageLoader` is used. If you would like to use an external ClientLoader, please refer to the [ClientLoader documentation](./client-loader.md).

**Note**: The `BaseImage` component extends the native `img` element, so any props used with `img` can be provided to the `BaseImage` component.

## Other Types


### OnLoadingComplete
```typescript
export type OnLoadingComplete = (result: {
Expand Down
Loading

0 comments on commit d87cc1d

Please sign in to comment.