`
+
+- `prefixDirname`: If the image is an ESM imported image, this is the directory name of the original file path; otherwise, it will be an empty string.
+- `baseFilename`: The base name of the file or a hashed short name if the file is a `data:` URI.
+- `hash`: A unique hash string generated to distinguish the transformed file.
+- `outputExtension`: The desired output file extension derived from the `transform.format` or the original file extension.
+
+```ts
+import { propsToFilename } from 'astro/assets';
+
+const filePath = '/images/photo.jpg';
+const transform = { format: 'png', src: filePath };
+const hash = 'abcd1234';
+
+const filename = propsToFilename(filePath, transform, hash);
+// Example value: '/images/photo_abcd1234.png'
+```
+
+### `hashTransform()`
+
+
+
+**Type:** (transform: ImageTransform, imageService: string, propertiesToHash: string[]) => string
+
+
+
+Transforms the provided `transform` object into a hash string based on selected properties and the specified `imageService`.
+
+```ts
+import { hashTransform } from 'astro/assets';
+
+const transform = {
+ src: '/images/photo.jpg',
+ width: 800,
+ height: 600,
+ format: 'jpg',
+};
+const imageService = 'astro/assets/services/sharp';
+const propertiesToHash = ['width', 'height', 'format'];
+
+const hash = hashTransform(transform, imageService, propertiesToHash);
+// Example value: 'd41d8cd98f00b204e9800998ecf8427e'
+```
+
## `astro/assets` types
The following types are imported from the regular assets module:
@@ -914,21 +950,14 @@ The following helpers are imported from the `utils` directory in the regular ass
```ts
import {
isRemoteAllowed,
- matchHostname,
- matchPathname,
matchPattern,
- matchPort,
- matchProtocol,
isESMImportedImage,
isRemoteImage,
resolveSrc,
imageMetadata,
- emitImageMetadata,
emitClientAsset,
getOrigQueryParams,
inferRemoteSize,
- propsToFilename,
- hashTransform,
} from "astro/assets/utils";
```
@@ -959,45 +988,6 @@ const remotePatterns = [
isRemoteAllowed(url.href, { domains, remotePatterns }); // Output: `true`
```
-### `matchHostname()`
-
-
-
-**Type:** `(url: URL, hostname?: string, allowWildcard = false) => boolean`
-
-
-
-Matches a given URL's hostname against a specified hostname, with optional support for wildcard patterns.
-
-```ts
-import { matchHostname } from 'astro/assets/utils';
-
-const url = new URL('https://sub.example.com/path/to/resource');
-
-matchHostname(url, 'example.com'); // Output: `false`
-matchHostname(url, 'example.com', true); // Output: `true`
-```
-
-### `matchPathname()`
-
-
-
-**Type:** `(url: URL, pathname?: string, allowWildcard = false) => boolean`
-
-
-
-Matches a given URL's pathname against a specified pattern, with optional support for wildcards.
-
-```ts
-import { matchPathname } from 'astro/assets/utils';
-
-const testURL = new URL('https://example.com/images/photo.jpg');
-
-matchPathname(testURL, '/images/photo.jpg'); // Output: `true`
-matchPathname(testURL, '/images/'); // Output: `false`
-matchPathname(testURL, '/images/*', true); // Output: `true`
-```
-
### `matchPattern()`
@@ -1021,48 +1011,6 @@ const remotePattern = {
matchPattern(url, remotePattern); // Output: `true`
```
-### `matchPort()`
-
-
-
-**Type:** `(url: URL, port?: string) => boolean`
-**Default:** `true`
-
-
-
-Checks if the given URL's port matches the specified port. If no port is provided, it returns `true`.
-
-```ts
-import { matchPort } from 'astro/assets/utils';
-
-const urlWithPort = new URL('https://example.com:8080/resource');
-const urlWithoutPort = new URL('https://example.com/resource');
-
-matchPort(urlWithPort, '8080'); // Output: `true`
-matchPort(urlWithoutPort, '8080'); // Output: `false`
-```
-
-### `matchProtocol()`
-
-
-
-**Type:** `(url: URL, protocol?: string) => boolean`
-**Default:** `true`
-
-
-
-Compares the protocol of the provided URL with a specified protocol. This returns `true` if the protocol matches or if no protocol is provided.
-
-```ts
-import { matchProtocol } from 'astro/assets/utils';
-
-const secureUrl = new URL('https://example.com/resource');
-const regularUrl = new URL('http://example.com/resource');
-
-matchProtocol(secureUrl, 'https'); // Output: `true`
-matchProtocol(regularUrl, 'https'); // Output: `false`
-```
-
### `isESMImportedImage()`
@@ -1163,31 +1111,6 @@ const metadata = await imageMetadata(binaryImage, sourcePath);
// }
```
-### `emitImageMetadata()`
-
-
-
-**Type:** (id: string | undefined, fileEmitter?: Rollup.EmitFile) => Promise\<(ImageMetadata & \{ contents?: Buffer \}) | undefined\>
-
-
-
-Processes an image file and emits its metadata and optionally its contents. In build mode, the function uses `fileEmitter` to generate an asset reference. In development mode, it resolves to a local file URL with query parameters for metadata.
-
-```ts
-import { emitImageMetadata } from 'astro/assets/utils';
-
-const imageId = '/images/photo.jpg';
-const metadata = await emitImageMetadata(imageId);
-// Example value:
-// {
-// src: '/@fs/home/username/dev/astro-project/src/images/photo.jpg?origWidth=800&origHeight=600&origFormat=jpg',
-// width: 800,
-// height: 600,
-// format: 'jpg',
-// contents: Uint8Array([...])
-// }
-```
-
### `emitClientAsset()`
@@ -1266,62 +1189,6 @@ const imageSize = await inferRemoteSize(remoteImageUrl);
// }
```
-### `propsToFilename()`
-
-
-
-**Type:** (filePath: string, transform: ImageTransform, hash: string) => string
-
-
-
-Generates a formatted filename for an image based on its source path, transformation properties, and a unique hash.
-
-The formatted filename follows this structure:
-
-`/_`
-
-- `prefixDirname`: If the image is an ESM imported image, this is the directory name of the original file path; otherwise, it will be an empty string.
-- `baseFilename`: The base name of the file or a hashed short name if the file is a `data:` URI.
-- `hash`: A unique hash string generated to distinguish the transformed file.
-- `outputExtension`: The desired output file extension derived from the `transform.format` or the original file extension.
-
-```ts
-import { propsToFilename } from 'astro/assets/utils';
-
-const filePath = '/images/photo.jpg';
-const transform = { format: 'png', src: filePath };
-const hash = 'abcd1234';
-
-const filename = propsToFilename(filePath, transform, hash);
-// Example value: '/images/photo_abcd1234.png'
-```
-
-### `hashTransform()`
-
-
-
-**Type:** (transform: ImageTransform, imageService: string, propertiesToHash: string[]) => string
-
-
-
-Transforms the provided `transform` object into a hash string based on selected properties and the specified `imageService`.
-
-```ts
-import { hashTransform } from 'astro/assets/utils';
-
-const transform = {
- src: '/images/photo.jpg',
- width: 800,
- height: 600,
- format: 'jpg',
-};
-const imageService = 'astro/assets/services/sharp';
-const propertiesToHash = ['width', 'height', 'format'];
-
-const hash = hashTransform(transform, imageService, propertiesToHash);
-// Example value: 'd41d8cd98f00b204e9800998ecf8427e'
-```
-
## `astro` types
```ts
@@ -1510,6 +1377,31 @@ Defines a list of allowed values for the `object-fit` CSS property, extensible w
Controls the value for the `object-position` CSS property.
+#### `ImageTransform.background`
+
+
+
+**Type:** `string | undefined`
+
+
+
+The background color to use when flattening an image to transform it into the requested output `format`.
+
+By default, Sharp uses a black background when flattening an image. Specifying a different background color is especially useful when transforming images with transparent backgrounds to a format that does not support transparency (e.g. `.jpeg`):
+
+```ts title="src/utils/images.ts"
+import { getImage } from "astro:assets";
+import myImage from "../my_image.png";
+
+const optimizedImage = await getImage({
+ src: myImage,
+ format: "jpeg",
+ background: "#ffffff"
+});
+```
+
+Values are passed directly to the image service. Sharp accepts [any value the `color-string` package can parse](https://github.com/Qix-/color-string/blob/master/README.md#parsing).
+
### `UnresolvedImageTransform`