Skip to content

feat: add more mention of needing to install Sharp manually #4498

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

Merged
Princesseuh merged 5 commits into from
Sep 1, 2023
Merged

feat: add more mention of needing to install Sharp manually #4498

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
8209629
feat: add more mention of needing to install Sharp manually
Princesseuh Sep 1, 2023
d8776f7
Merge branch 'main' into feat/mention-pnpm-sharp-everywhere
Princesseuh Sep 1, 2023
90eb4b9
Update src/content/docs/en/guides/upgrade-to/v3.mdx
Princesseuh Sep 1, 2023
2265ee9
Update src/content/docs/en/guides/images.mdx
Princesseuh Sep 1, 2023
33c4ead
Merge branch 'main' into feat/mention-pnpm-sharp-everywhere
Princesseuh Sep 1, 2023
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
24 changes: 16 additions & 8 deletions src/content/docs/en/guides/images.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,15 @@ Astro provides several ways for you to use images on your site, whether they are

### `src/` vs `public/`

We recommend that local images are kept in `src/` when possible so that Astro can transform, optimize and bundle them. Files in the `/public` directory are always served or copied into the build folder as-is, with no processing.
We recommend that local images are kept in `src/` when possible so that Astro can transform, optimize and bundle them. Files in the `/public` directory are always served or copied into the build folder as-is, with no processing.

Your local images stored in `src/` can be used by all files in your project: `.astro`, `.md`, `.mdx`, `.mdoc`, and other UI frameworks. Images can be stored in any folder, including alongside your content.

Store your images in the `public/` folder if you want to avoid any processing or to have a direct public link to them.

### Remote images

You can also choose to store your images remotely, in a content management system (CMS) or digital asset management (DAM) platform.
You can also choose to store your images remotely, in a content management system (CMS) or digital asset management (DAM) platform.

For extra protection when dealing with external sources, remote images will only be processed from [authorized image sources](#authorizing-remote-images) specified in your configuration. However, any remote images can be displayed.

Expand All @@ -32,7 +32,7 @@ Astro can fetch your data remotely using APIs or display images from their full

In `.astro` files, local images must be imported into the file in order to be used. Remote and `public/` images do not require importing.

Import and use Astro's built-in `<Image />` component for optimized images using `astro:assets`. Alternatively, Astro syntax supports writing an HTML `<img>` tag directly, which skips image processing.
Import and use Astro's built-in `<Image />` component for optimized images using `astro:assets`. Alternatively, Astro syntax supports writing an HTML `<img>` tag directly, which skips image processing.

```astro title="src/pages/blog/MyImages.astro"
---
Expand Down Expand Up @@ -110,7 +110,7 @@ The format of the `src` value of your image file depends on where your image fil
---
import { Image } from 'astro:assets';
---
<Image
<Image
src="/images/my-public-image.png"
alt="descriptive text"
width="200"
Expand All @@ -124,7 +124,7 @@ The format of the `src` value of your image file depends on where your image fil
---
import { Image } from 'astro:assets';
---
<Image
<Image
src="https://example.com/remote-image.jpg"
alt="descriptive text"
width="200"
Expand All @@ -145,7 +145,7 @@ When using local images in their original aspect ratio, the `width` and `height`

However, both of these properties are required for remote images and images stored in your `public/` folder as Astro is unable to analyze these files.

##### format
##### format

You can optionally state the [image file type](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types#common_image_file_types) output to be used.

Expand Down Expand Up @@ -392,7 +392,7 @@ export const collections = {
};
```

The image will be imported and transformed into metadata, allowing you to pass it as a `src` to `<Image/>`, `<img>`, or `getImage()`.
The image will be imported and transformed into metadata, allowing you to pass it as a `src` to `<Image/>`, `<img>`, or `getImage()`.

The example below shows a blog index page that renders the cover photo and title of each blog post from the schema above:

Expand Down Expand Up @@ -514,6 +514,14 @@ export default defineConfig({
});
```

:::note
When using a [strict package manager](https://pnpm.io/pnpm-vs-npm#npms-flat-tree) like `pnpm`, you may need to manually install Sharp into your project even though it is an Astro dependency:

```bash
pnpm install sharp
```
:::

## Community Integrations

There are several third-party [community image integrations](https://astro.build/integrations?search=images) for optimizing and working with images in your Astro project.
Expand All @@ -526,7 +534,7 @@ There are several third-party [community image integrations](https://astro.build

These and other accompanying changes to using images in Astro may cause some breaking changes when you upgrade your Astro project from an earlier version.

Please follow the instructions below as appropriate to upgrade an Astro v2.x project to v3.0.
Please follow the instructions below as appropriate to upgrade an Astro v2.x project to v3.0.

### Upgrade from `experimental.assets`

Expand Down
27 changes: 17 additions & 10 deletions src/content/docs/en/guides/upgrade-to/v3.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Update your project's version of Astro to the latest version using your package
```shell
# Upgrade to Astro v3.x
npm install astro@latest

# Example: upgrade React and Tailwind integrations
npm install @astrojs/react@latest @astrojs/tailwind@latest
```
Expand All @@ -38,7 +38,7 @@ Update your project's version of Astro to the latest version using your package
```shell
# Upgrade to Astro v3.x
yarn add astro@latest

# Example: upgrade React and Tailwind integrations
yarn add @astrojs/react@latest @astrojs/tailwind@latest
```
Expand Down Expand Up @@ -84,7 +84,7 @@ See [the changelog](https://github.com/withastro/astro/blob/main/packages/astro/

### Removed: Support for Node 16

Node 16 is scheduled to reach its End of Life in September 2023.
Node 16 is scheduled to reach its End of Life in September 2023.

Astro v3.0 drops Node 16 support entirely so that all Astro users can take advantage of Node's more modern features.

Expand All @@ -100,7 +100,7 @@ Astro v3.0 drops Node 16 support entirely so that all Astro users can take advan



2. Check your [deployment environment's](/en/guides/deploy/) own documentation to verify that they support Node 18.
2. Check your [deployment environment's](/en/guides/deploy/) own documentation to verify that they support Node 18.

You can specify Node `18.14.1` for your Astro project either in a dashboard configuration setting or a `.nvmrc` file.

Expand Down Expand Up @@ -163,7 +163,7 @@ import Markdown from '@astrojs/markdown-component';
---
```

To continue using a similar `<Markdown />` component in your code, consider using [community integrations](https://astro.build/integrations/) such as [`astro-remote`](https://github.com/natemoo-re/astro-remote). Be sure to update your `<Markdown />` component imports and attributes as necessary, according to the integration's own documentation.
To continue using a similar `<Markdown />` component in your code, consider using [community integrations](https://astro.build/integrations/) such as [`astro-remote`](https://github.com/natemoo-re/astro-remote). Be sure to update your `<Markdown />` component imports and attributes as necessary, according to the integration's own documentation.

Otherwise, delete all references to importing Astro's `<Markdown />` component and the component itself in your `.astro` files. You will need to rewrite your content as HTML directly or [import Markdown](/en/guides/markdown-content/#importing-markdown) from a `.md` file.

Expand Down Expand Up @@ -203,7 +203,7 @@ If you are using the deprecated `image()` from `astro:content`, remove it as thi
```ts title="astro.config.mjs" del={1} ins={2} "({ image })"
import { defineCollection, z, image } from "astro:content";
import { defineCollection, z } from "astro:content";

defineCollection({
schema: ({ image }) =>
z.object({
Expand Down Expand Up @@ -243,7 +243,7 @@ Replace any `Set` elements passed to the `class:list` directive with a plain `Ar
'a',
'b',
new Set(['c', 'd'])
['c', 'd']
['c', 'd']
]} />
```

Expand Down Expand Up @@ -485,7 +485,7 @@ Astro v3.0 introduces a new, default value: `"attribute"`. By default, styles ar

#### What should I do?

To retain your project's current [style scoping](/en/guides/styling/#scoped-styles), update the configuration file to the previous default value:
To retain your project's current [style scoping](/en/guides/styling/#scoped-styles), update the configuration file to the previous default value:


```js title="astro.config.mjs" ins={4}
Expand Down Expand Up @@ -524,7 +524,15 @@ Astro v3.0 now includes Sharp as the default image processing service and instea

#### What should I do?

If you would prefer to continue to use Squoosh to transform your images, update your config with the following:
:::note
When using a [strict package manager](https://pnpm.io/pnpm-vs-npm#npms-flat-tree) like `pnpm`, you may need to manually install Sharp into your project even though it is an Astro dependency:

```bash
pnpm install sharp
```
:::

If you would prefer to continue to use Squoosh to transform your images, update your config with the following:

```ts title="astro.config.mjs" ins={4-6}
import { defineConfig, squooshImageService } from "astro/config";
Expand Down Expand Up @@ -675,4 +683,3 @@ Know a good resource for Astro v3.0? [Edit this page](https://github.com/withast
## Known Issues

There are currently no known issues.