Astro integration for image compression and conversion, superseding Astro's default image service.
npm install astro-better-image-service
astro-better-image-service is an Astro integration for image compression and conversion, superseding Astro's default image service.
- Compress raster images with the maximum compression ratio using sharp.
- Compress SVG images using svgo.
- Convert SVG images to raster images using sharp.
- And, of course, all features of Astro's default image service (sharpImageService) are supported.
Run the following command and it will automatically install the package and add the integration to your astro.config.{ts,js,mjs,cjs} file.
``bash`
bun astro add astro-better-image-service
`bash`
npx astro add astro-better-image-service
1. Add this npm package to dependencies.
`bash`
bun add astro-better-image-service
`bash`
npm install astro-better-image-service
2. Edit your Astro configuration file to include the integration.
astro.config.{ts,js,mjs,cjs}
`javascript
import betterImageService from "astro-better-image-service";
import { defineConfig } from "astro/config";
export default defineConfig({
// ...
integrations: [
// ... other integrations
betterImageService(),
// ... other integrations
],
// ...
});
`
You may put the betterImageService integration anywhere in the integrations array.
Please note that this integration cannot be used with other integrations using the Image Service API. (I haven't seen any yet.)
This integration is built using Astro's Image Service API.
It enables us to use all the awesome features of Astro, for example, caching, lazy loading, and more listed in the Astro Images documentation.
Image optimization with the maximum compression ratio may slow down your build time.
You are discouraged using this integration in SSR environments, because it may slow down the responses.
- The default image service (a.k.a. astro:assets) uses the default compression settings of sharp, in which the compression ratio is medium, as referred to in the Astro Discord.
> astro-compress sets the compression level to the maximum, whereas astro:assets uses the default settings
> We most likely could tune up the settings a bit, though we need to be careful about it taking too much time (notably because of SSR doing it at runtime)
> see:
- The default image service does not support SVG images.
It only passes them through without any optimization.
Also, it does not support converting SVG images to raster images. (format option is ignored)
)- @playform/compress does not cache compressed images, so slows down your build time.
- @playform/compress does not support converting SVG images to raster images. outDir
\* It only compresses built files in , and does not intercept the build process.
- Unless you set image.service in astro.config.{ts,js,mjs,cjs} to passthroughImageService, Astro optimizes images and @playform/compress compresses them again.
Since astro-better-image-service does not support optimizing HTML, CSS, and JavaScript files, you may use @playform/compress with it to compress them.
For example, you may use the following configuration.
astro.config.{ts,js,mjs,cjs}
`javascript
import betterImageService from "astro-better-image-service";
import compress from "@playform/compress";
import { defineConfig } from "astro/config";
export default defineConfig({
integrations: [
betterImageService(),
compress({
Image: false,
SVG: false,
}),
],
});
`
If you want to configure the configuration of the image compression and conversion, you may pass a configuration object to the betterImageService function. defaultConfig
The configuration object is merged with the default configuration object, exported as from the package.
astro.config.{ts,js,mjs,cjs}
`javascript
import betterImageService from "astro-better-image-service";
import { defineConfig } from "astro/config";
export default defineConfig({
// ...
integrations: [
betterImageService({
sharp: {
sharp: {
// sharp constructor options
},
png: {
// sharp png options
},
jpeg: {
// sharp jpeg options
},
webp: {
// sharp webp options
},
avif: {
// sharp avif options
},
},
svgo: {
// svgo options
},
}),
],
// ...
});
`
You cannot configure image.service.config.limitInputPixels in the configuration object unless you set the image.service.entrypoint to sharpImageService. limitInputPixels
We support to set in the configuration object of betterImageService for compatibility with the default image service. sharp.sharp.limitInputPixels
However, we recommend setting in the configuration object of betterImageService for clarity. limitInputPixels
For example, you may set to false as follows.
astro.config.{ts,js,mjs,cjs}
`javascript
import betterImageService from "astro-better-image-service";
import { defineConfig } from "astro/config";
export default defineConfig({
// ...
integrations: [
betterImageService({
// not recommended
limitInputPixels: false,
// recommended
sharp: {
sharp: {
limitInputPixels: false,
},
},
}),
],
// ...
});
`
Run the following commands to start development.
`bash`
gh repo clone risu729/astro-better-image-service
cd astro-better-image-service
mise install
To test this package, you may link it to a project using it by running the following commands.
`bash`
mise run devin a project using astro-better-image-service
bun link astro-better-image-service
E2E tests using Playwright run on GitHub Actions.
To commit, run the following command.
commitizen will ask you to fill in the commit message.
`bash`
mise run commitor to commit only staged files
mise run commit --staged
This package is released automatically by GitHub Actions using semantic-release.
package.json#version is not updated in git, but automatically updated and published to npm.
MIT License
- Astro team and community for the project and the powerful Image Service API.
- sharp and svgo contributors for the awesome image processing libraries.
- Playform for the inspiration from the @playform/compress` package.