Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(image_services): Add mention of new validateOptions hook #2859

Merged
merged 2 commits into from
Mar 21, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 15 additions & 6 deletions src/content/docs/en/reference/image-service-reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,13 @@ Astro provides two types of image services: Local and External.

## Building using the Image Services API

Service definitions take the shape of an exported default object with various required methods ("hooks").
Service definitions take the shape of an exported default object with various required methods ("hooks").

External services provide a `getURL()` that points to the `src` of the output `<img>` tag.

Local services provide a `transform()` method to perform transformations on your image, and `getURL()` and `parseURL()` methods to use an endpoint for dev mode and SSR.
Local services provide a `transform()` method to perform transformations on your image, and `getURL()` and `parseURL()` methods to use an endpoint for dev mode and SSR.

Both types of services can provide `getHTMLAttributes()` to determine the other attributes of the output `<img>`.
Both types of services can provide `getHTMLAttributes()` to determine the other attributes of the output `<img>` and `validateOptions()` to validate and augment the passed options.

### External Services

Expand Down Expand Up @@ -112,9 +112,9 @@ const service: LocalImageService = {
export default service;
```

At build time for static sites and pre-rendered routes, both `<Image/>` and `getImage(options)` call the `transform()` function. They pass options either through component attributes or an `options` argument, respectively. The transformed images will be built to a `dist/_astro` folder.
At build time for static sites and pre-rendered routes, both `<Image />` and `getImage(options)` call the `transform()` function. They pass options either through component attributes or an `options` argument, respectively. The transformed images will be built to a `dist/_astro` folder.

In dev mode and SSR mode, Astro doesn't know ahead of time which images need to be optimized. Astro uses a GET endpoint (by default, (`/_image`) to process the images at runtime. `<Image/>` and `getImage()` pass their options to `getURL()`, which will return the endpoint URL. Then, the endpoint calls `parseURL()` and passes the resulting properties to `transform()`.
In dev mode and SSR mode, Astro doesn't know ahead of time which images need to be optimized. Astro uses a GET endpoint (by default, `/_image`) to process the images at runtime. `<Image />` and `getImage()` pass their options to `getURL()`, which will return the endpoint URL. Then, the endpoint calls `parseURL()` and passes the resulting properties to `transform()`.

#### getConfiguredImageService

Expand All @@ -135,12 +135,13 @@ export const get: APIRoute = async ({ request }) => {
headers: {
'Content-Type': mime.getType(format) || ''
}
}
);
}
```

[See the built-in endpoint](https://github.com/withastro/astro/blob/main/packages/astro/src/assets/image-endpoint.ts) for a full example.


## Hooks

Expand Down Expand Up @@ -196,6 +197,14 @@ You must return a `format` to ensure that the proper MIME type is served to user

This hook returns all additional attributes used to render the image as HTML, based on the parameters passed by the user (`options`).

### `validateOptions()`

**Optional for both local and external services**

`validateOptions(options: ImageTransform): ImageTransform`

This hook allows you to validate and augment the options passed by the user. This is useful for setting default options, or telling the user that a parameter is required.

## User configuration

Configure the image service to use in `astro.config.mjs`. The config takes the following form:
Expand Down