Images

          
            ## Astro Images Guidelines

1.  Image Storage:

    - `src/` (Recommended): Place images anywhere inside `src/` (e.g., `src/assets/`). Astro processes, optimizes, and bundles these images. Import them into your files to use.
      ```astro
      ---
      import localImage from '../assets/logo.png';
      ---
      ```
    - `public/`: Place images here if they should _not_ be processed by Astro and need a direct public URL. Reference them using a root-relative path (e.g., `/images/hero.jpg`).
    - Remote: Images hosted externally (CMS, CDN). Reference using their full URL. Remote domains _must_ be authorized in `astro.config.mjs` to be processed by `<Image />` or `<Picture />`.

2.  Using Images in `.astro` Files:

    - `<Image />` Component (from `astro:assets`): For optimized images. Automatically handles resizing, format conversion, and adds performance/accessibility attributes.

      - Required Props: `src`, `alt`, `width`, `height`.
      - `src`: Can be an imported local image object (`import img from '...'`) or an authorized remote URL string.

      ```astro
      ---
      import { Image } from 'astro:assets';
      import localLogo from '../assets/logo.png';
      ---
      <!-- Local Image -->
      <Image src={localLogo} width={300} height={150} alt="Astro Logo" />

      <!-- Remote Image (domain must be authorized) -->
      <Image src="https://example.com/remote.jpg" width={800} height={600} alt="Remote Image" />

      <!-- Public Image (no optimization) -->
      <Image src="/images/public-image.png" width={100} height={100} alt="Public Image" />
      ```

    - `<Picture />` Component (from `astro:assets`): For responsive images, providing different formats and sizes.
      - Required Props: `src`, `alt`, `widths`, `formats`.
      ```astro
      ---
      import { Picture } from 'astro:assets';
      import responsiveImg from '../assets/responsive.jpg';
      ---
      <Picture src={responsiveImg} widths={[200, 400, 800]} formats={['avif', 'webp']} alt="Responsive" />
      ```
    - HTML `<img>` Tag: For basic, unprocessed images.

      - Local Image: Import the image first, then use the `.src` property.
      - Public/Remote Image: Use the direct URL path.

      ```astro
      ---
      import localImage from '../assets/unprocessed.png';
      ---
      <!-- Local Image -->
      <img src={localImage.src} width={localImage.width} height={localImage.height} alt="Unprocessed" />

      <!-- Public Image -->
      <img src="/images/public-raw.jpg" alt="Public Raw" />

      <!-- Remote Image -->
      <img src="https://example.com/raw-remote.gif" alt="Remote Raw" />
      ```

3.  Authorizing Remote Domains: To allow Astro's built-in image service to process remote images used in `<Image />` or `<Picture />`, list the domains or URL patterns in `astro.config.mjs`:

    ```javascript
    // astro.config.mjs
    import { defineConfig } from "astro/config";

    export default defineConfig({
      image: {
        // Simple domain list
        domains: ["astro.build", "example.com"],
        // Or more complex patterns
        remotePatterns: [{ protocol: "https", hostname: "**.cdn.net" }],
      },
    });
    ```

4.  Images in Markdown (`.md`) and MDX (`.mdx`):

    - Standard Markdown Syntax: `![alt text](mdc:path/to/image.jpg)` works for relative paths (to the Markdown file), paths in `public/`, and remote URLs. Images are _not_ optimized by default with this syntax.
    - MDX: Can additionally use imported images with `<Image />`, `<Picture />`, or `<img>` tags just like in `.astro` files.

5.  Images in Content Collections:

    - Use the `image()` helper from `astro:content` in your collection schema (`z.object({ cover: image() })`).
    - Reference the image file path relative to the content file in the frontmatter (`cover: './cover-image.png'`).
    - The `image()` helper imports and processes the image, returning metadata suitable for the `src` prop of `<Image />` or `getImage()`.

6.  Images in UI Framework Components (React, Vue, etc.):

    - The Astro `<Image />` and `<Picture />` components cannot be used directly _inside_ framework components.
    - Option 1: Pass the rendered `<Image />` from an `.astro` parent component via children or `<slot />`.
    - Option 2: Use the framework's native image tag (e.g., JSX `<img />`). Import the local image within the framework component file to get its properties (`src`, `width`, `height`).

7.  `getImage()` Utility (from `astro:assets`):

    - A function to programmatically generate image metadata (`src`, `attributes`, etc.) based on options.
    - Useful for scenarios where components aren't suitable (e.g., API routes, custom components).

8.  Accessibility (`alt` Text):

    - Required for `<Image />` and `<Picture />`. Provide descriptive text.
    - Use `alt=""` for purely decorative images that don't add information.

9.  Image Service Configuration:
    - Sharp is the default service for optimization (may require manual install: `pnpm add sharp`).
    - Can be configured via `image.service` in `astro.config.mjs`.
    - Use `passthroughImageService()` for environments where Sharp isn't supported (e.g., Cloudflare Pages, Deno). This allows using `<Image />`/`<Picture />` syntax but skips optimization.

Reference: [Astro Images Docs](mdc:https:/docs.astro.build/en/guides/images)