Skip to content

docs: fix outdated astro:assets imports and snippets #14478

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.

Sign up for GitHub

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

Closed
Nloperena wants to merge 1 commit into from
+89 −199
Closed

docs: fix outdated astro:assets imports and snippets #14478

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
14 changes: 6 additions & 8 deletions src/content/docs/en/guides/upgrade-to/v6.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -713,24 +713,22 @@ import { ClientRouter } from 'astro:transitions';

<SourcePR number="14426" title="feat!: remove emitESMImage()"/>

In Astro 5.6.2, the `emitESMImage()` function was deprecated in favor of `emitImageMetadata()`, which removes two deprecated arguments that were not meant to be exposed for public use: `_watchMode` and `experimentalSvgEnabled`.

Astro 6.0 removes `emitESMImage()` entirely. Update to `emitImageMetadata()` to keep your current behavior.
In Astro 5.6.2, the `emitESMImage()` function was deprecated. Astro 6.0 removes `emitESMImage()` entirely.

#### What should I do?

Replace all occurrences of the `emitESMImage()` with `emitImageMetadata()` and remove unused arguments:
Remove all occurrences of `emitESMImage()`:

```ts del={1,5} ins={2,6}
```ts del={1,4}
import { emitESMImage } from 'astro/assets/utils';
import { emitImageMetadata } from 'astro/assets/utils';

const imageId = '/images/photo.jpg';
const result = await emitESMImage(imageId, false, false);
const result = await emitImageMetadata(imageId);
```

<ReadMore>Read more about [`emitImageMetadata()`](/en/reference/modules/astro-assets/#emitimagemetadata).</ReadMore>
:::note
The previously recommended replacement `emitImageMetadata()` has also been removed from `astro/assets/utils`.
:::

### Removed: `Astro.glob()`

Expand Down
274 changes: 83 additions & 191 deletions src/content/docs/en/reference/modules/astro-assets.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -440,28 +440,6 @@ Defines the position of the image crop for a image if the aspect ratio is change

Values match those of CSS `object-position`. Defaults to `center`, or the value of [`image.objectPosition`](/en/reference/configuration-reference/#imageobjectposition) if set. Can be used to override the default `object-position` styles.

#### `background`

<p>

**Type:** `string | undefined`<br />
<Since v="5.17.0" />
</p>

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`):

```astro title="src/components/MyComponent.astro" "background"
<Image
src={myImage}
alt="A description of my image"
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).

### `<Picture />`

Expand Down Expand Up @@ -841,6 +819,8 @@ import {
getConfiguredImageService,
getImage,
isLocalService,
propsToFilename,
hashTransform,
} from "astro/assets";
```

Expand Down Expand Up @@ -888,6 +868,62 @@ A function similar to [`getImage()`](#getimage) from `astro:assets` with two req

Checks the type of an image service and returns `true` when this is a [local service](#localimageservice).

### `propsToFilename()`

<p>

**Type:** <code>(filePath: string, transform: <a href="#imagetransform">ImageTransform</a>, hash: string) => string</code><br />
<Since v="4.0.0" />
</p>

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>/<baseFilename>_<hash><outputExtension>`

- `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()`

<p>

**Type:** <code>(transform: <a href="#imagetransform">ImageTransform</a>, imageService: string, propertiesToHash: string[]) => string</code><br />
<Since v="4.0.0" />
</p>

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:
Expand All @@ -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";
```

Expand Down Expand Up @@ -959,45 +988,6 @@ const remotePatterns = [
isRemoteAllowed(url.href, { domains, remotePatterns }); // Output: `true`
```

### `matchHostname()`

<p>

**Type:** `(url: URL, hostname?: string, allowWildcard = false) => boolean`<br />
<Since v="4.0.0" />
</p>

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()`

<p>

**Type:** `(url: URL, pathname?: string, allowWildcard = false) => boolean`<br />
<Since v="4.0.0" />
</p>

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()`

<p>
Expand All @@ -1021,48 +1011,6 @@ const remotePattern = {
matchPattern(url, remotePattern); // Output: `true`
```

### `matchPort()`

<p>

**Type:** `(url: URL, port?: string) => boolean`<br />
**Default:** `true`<br />
<Since v="4.0.0" />
</p>

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()`

<p>

**Type:** `(url: URL, protocol?: string) => boolean`<br />
**Default:** `true`<br />
<Since v="4.0.0" />
</p>

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()`

<p>
Expand Down Expand Up @@ -1163,31 +1111,6 @@ const metadata = await imageMetadata(binaryImage, sourcePath);
// }
```

### `emitImageMetadata()`

<p>

**Type:** <code>(id: string | undefined, fileEmitter?: Rollup.EmitFile) => Promise\<(<a href="#imagemetadata-1">ImageMetadata</a> & \{ contents?: Buffer \}) | undefined\></code><br />
<Since v="5.7.0" />
</p>

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()`

Expand Down Expand Up @@ -1266,62 +1189,6 @@ const imageSize = await inferRemoteSize(remoteImageUrl);
// }
```

### `propsToFilename()`

<p>

**Type:** <code>(filePath: string, transform: <a href="#imagetransform">ImageTransform</a>, hash: string) => string</code><br />
<Since v="4.0.0" />
</p>

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>/<baseFilename>_<hash><outputExtension>`

- `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()`

<p>

**Type:** <code>(transform: <a href="#imagetransform">ImageTransform</a>, imageService: string, propertiesToHash: string[]) => string</code><br />
<Since v="4.0.0" />
</p>

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
Expand Down Expand Up @@ -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`

<p>

**Type:** `string | undefined`<br />
<Since v="5.17.0" />
</p>

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`

<p>
Expand Down
Loading