updating the README for squoosh
This commit is contained in:
Tony Sullivan
parent
1478809282
commit
8f099ced3f
1 changed files with 41 additions and 4 deletions
|
|
@ -18,7 +18,7 @@ This **[Astro integration][astro-integration]** makes it easy to optimize images
|
|||
|
||||
Images play a big role in overall site performance and usability. Serving properly sized images makes all the difference but is often tricky to automate.
|
||||
|
||||
This integration provides `<Image />` and `<Picture>` components as well as a basic image transformer powered by [sharp](https://sharp.pixelplumbing.com/), with full support for static sites and server-side rendering. The built-in `sharp` transformer is also replaceable, opening the door for future integrations that work with your favorite hosted image service.
|
||||
This integration provides `<Image />` and `<Picture>` components as well as a basic image transformer, with full support for static sites and server-side rendering. The built-in image transformer is also replaceable, opening the door for future integrations that work with your favorite hosted image service.
|
||||
|
||||
## Installation
|
||||
|
||||
|
|
@ -57,6 +57,31 @@ export default {
|
|||
}
|
||||
```
|
||||
|
||||
### Installing `sharp` (optional)
|
||||
|
||||
The default image transformer is based on [Squoosh](https://github.com/GoogleChromeLabs/squoosh) and uses web assembly libraries to support most deployment environments.
|
||||
|
||||
If you are building a static site or using an SSR deployment host that supports NodeJS, we recommend installing [sharp](https://sharp.pixelplumbing.com/) for faster builds and more fine-grained control of image transformations.
|
||||
|
||||
|
||||
First, install the `sharp` package using your package manger. If you're using npm or aren't sure, run this in the terminal:
|
||||
```sh
|
||||
npm install sharp
|
||||
```
|
||||
Then, update the integration in you `astro.config.*` file to use the built-in `sharp` image transformer.
|
||||
```astro title="astro.config.mjs"
|
||||
---
|
||||
import image from '@astrojs/image';
|
||||
|
||||
export default {
|
||||
// ...
|
||||
integrations: [image({
|
||||
serviceEntryPoint: '@astrojs/image/sharp'
|
||||
})],
|
||||
}
|
||||
---
|
||||
```
|
||||
|
||||
### Update `env.d.ts`
|
||||
|
||||
For the best development experience, add the integrations type definitions to your project's `env.d.ts` file.
|
||||
|
|
@ -85,7 +110,7 @@ import { Image, Picture } from '@astrojs/image/components';
|
|||
---
|
||||
```
|
||||
|
||||
The included `sharp` transformer supports resizing images and encoding them to different image formats. Third-party image services will be able to add support for custom transformations as well (ex: `blur`, `filter`, `rotate`, etc).
|
||||
The included image transformers support resizing images and encoding them to different image formats. Third-party image services will be able to add support for custom transformations as well (ex: `blur`, `filter`, `rotate`, etc).
|
||||
|
||||
Astro’s `<Image />` and `<Picture />` components require the `alt` attribute, which provides descriptive text for images. A warning will be logged if alt text is missing, and a future release of the integration will throw an error if no alt text is provided.
|
||||
|
||||
|
|
@ -195,6 +220,8 @@ A `number` can also be provided, useful when the aspect ratio is calculated at b
|
|||
**Default:** `undefined`
|
||||
</p>
|
||||
|
||||
> This is not supported by the default Squoosh service. See the [installation section](#installing-sharp-optional) for details on using the `sharp` service instead.
|
||||
|
||||
The background color to use for replacing the alpha channel with `sharp`'s `flatten` method. In case the output format
|
||||
doesn't support transparency (i.e. `jpeg`), it's advisable to include a background color, otherwise black will be used
|
||||
as default replacement for transparent pixels.
|
||||
|
|
@ -213,6 +240,8 @@ color representation with 3 or 6 hexadecimal characters in the form `#123[abc]`,
|
|||
**Default:** `'cover'`
|
||||
</p>
|
||||
|
||||
> This is not supported by the default Squoosh service. See the [installation section](#installing-sharp-optional) for details on using the `sharp` service instead.
|
||||
|
||||
How the image should be resized to fit both `height` and `width`.
|
||||
|
||||
#### position
|
||||
|
|
@ -223,6 +252,8 @@ How the image should be resized to fit both `height` and `width`.
|
|||
**Default:** `'centre'`
|
||||
</p>
|
||||
|
||||
> This is not supported by the default Squoosh service. See the [installation section](#installing-sharp-optional) for details on using the `sharp` service instead.
|
||||
|
||||
Position of the crop when fit is `cover` or `contain`.
|
||||
|
||||
### `<Picture />`
|
||||
|
|
@ -314,6 +345,8 @@ The output formats to be used in the optimized image. If not provided, `webp` an
|
|||
**Default:** `undefined`
|
||||
</p>
|
||||
|
||||
> This is not supported by the default Squoosh service. See the [installation section](#installing-sharp-optional) for details on using the `sharp` service instead.
|
||||
|
||||
The background color to use for replacing the alpha channel with `sharp`'s `flatten` method. In case the output format
|
||||
doesn't support transparency (i.e. `jpeg`), it's advisable to include a background color, otherwise black will be used
|
||||
as default replacement for transparent pixels.
|
||||
|
|
@ -332,6 +365,8 @@ color representation with 3 or 6 hexadecimal characters in the form `#123[abc]`,
|
|||
**Default:** `'cover'`
|
||||
</p>
|
||||
|
||||
> This is not supported by the default Squoosh service. See the [installation section](#installing-sharp-optional) for details on using the `sharp` service instead.
|
||||
|
||||
How the image should be resized to fit both `height` and `width`.
|
||||
|
||||
#### position
|
||||
|
|
@ -344,6 +379,8 @@ How the image should be resized to fit both `height` and `width`.
|
|||
**Default:** `'centre'`
|
||||
</p>
|
||||
|
||||
> This is not supported by the default Squoosh service. See the [installation section](#installing-sharp-optional) for details on using the `sharp` service instead.
|
||||
|
||||
Position of the crop when fit is `cover` or `contain`.
|
||||
|
||||
### `getImage`
|
||||
|
|
@ -378,12 +415,12 @@ This helper takes in an object with the same properties as the `<Picture />` com
|
|||
|
||||
The integration can be configured to run with a different image service, either a hosted image service or a full image transformer that runs locally in your build or SSR deployment.
|
||||
|
||||
> During development, local images may not have been published yet and would not be available to hosted image services. Local images will always use the built-in `sharp` service when using `astro dev`.
|
||||
> During development, local images may not have been published yet and would not be available to hosted image services. Local images will always use the built-in image service when using `astro dev`.
|
||||
|
||||
|
||||
### config.serviceEntryPoint
|
||||
|
||||
The `serviceEntryPoint` should resolve to the image service installed from NPM. The default entry point is `@astrojs/image/sharp`, which resolves to the entry point exported from this integration's `package.json`.
|
||||
The `serviceEntryPoint` should resolve to the image service installed from NPM. The default entry point is `@astrojs/image/squoosh`, which resolves to the entry point exported from this integration's `package.json`.
|
||||
|
||||
```js
|
||||
// astro.config.mjs
|
||||
|
|
|
|||
Loading…
Reference in a new issue