Imagens

Astro fornece diversas formas de utilizar imagens no seu site, sejam elas armazenadas localmente dentro do seu projeto, vinculadas de uma URL externa, ou gerenciadas em um CMS ou CDN!

Onde armazenar imagens

`src/` vs `public/`

Nós recomendamos que imagens locais sejam mantidas em src/ quando possível para que o Astro possa transformar, otimizar e fazer bundle delas. Arquivos no diretório /public sempre são servidos ou copiados para a pasta da build como estão, sem nenhum processamento.

Suas imagens locais armazenadas em src/ podem ser usadas por todos os arquivos em seu projeto: .astro, .md, .mdx, .mdoc, e outros frameworks de UI. As imagens podem ser armazenadas em qualquer pasta, inclusive junto com o conteúdo.

Armazene suas imagens na pasta public/ se você quer evitar qualquer processamento ou para ter um link público direto para elas.

Imagens remotas

Você também pode escolher armazenar suas imagens remotamente, em um sistema de gerenciamento de conteúdo (CMS, do inglês “content management system”) ou plataforma de gerenciamento de assets digitais (DAM, do inglês “digital asset management”).

Para proteção extra ao lida com fontes externas, imagens remotas serão apenas processadas de fontes de imagem autorizadas especificadas na sua configuração. Contudo, quaisquer imagens remotas podem ser mostradas.

Astro pode buscar dados remotamente usando APIs ou mostrar imagens a partir de seus caminhos de URL completos. Veja nossos guias de CMS para exemplos de integração de serviços comuns.

Imagens em arquivos `.astro`

Em arquivos .astro, imagens locais devem ser importadas no arquivo para que sejam utilizadas. Imagens remotas e de public/ não precisam ser importadas.

Importe e utilize o componente <Image /> integrado do Astro para imagens otimizadas utilizando astro:assets. Alternativamente, a sintaxe do Astro suporta escrever uma tag <img> do HTML diretamente, o que pula o processamento de imagem.

---
import { Image } from 'astro:assets';
import imagemPassaroLocal from '../../imagens/subpasta/imagemPassaroLocal.png';
---
<Image src={imagemPassaroLocal} alt="Um pássaro sentando em um ninho de ovos."/>
<Image src="/imagens/passaro-na-pasta-public.jpg" alt="Um pássaro." width="50" height="50"/>
<Image src="https://exemplo.com/passaro-remoto.jpg" alt="Um pássaro." width="50" height="50"/>

<img src={imagemPassaroLocal.src} alt="Um pássaro sentando em um ninho de ovos.">
<img src="/imagens/passaro-na-pasta-public.jpg" alt="Um pássaro.">
<img src="https://exemplo.com/passaro-remoto.jpg" alt="Um pássaro.">

Para importar imagens dinamicamente do diretório src/, veja a seguinte receita:

Receita relacionada: Dynamically import images (EN)

`<Image />` (`astro:assets`)

Utilize o componente <Image /> integrado do Astro para mostrar versões otimizadas de suas imagens locais e imagens remotas configuradas.

Imagens na pasta public/, assim como imagens remotas não especificadamente configuradas no seu projeto, também podem ser usadas com o componente Image, mas não serão processadas.

<Image /> pode transformar as dimensões, o tipo de arquivo e a qualidade de uma imagem local ou remota autorizada para controlar a imagem exibida. A tag <img> resultante inclui os atributos alt, loading e decoding e infere as dimensões da imagem para evitar Cumulative Layout Shift (CLS).

---
// importe o componente Image e a imagem
import { Image } from 'astro:assets';
import minhaImagem from "../assets/minha_imagem.png"; // Imagem é 1600x900
---

<!-- `alt` é obrigatório no componente Image -->
<Image src={minhaImagem} alt="Uma descrição da minha imagem." />

<!-- Resultado -->
<!-- Imagem é otimizada, atributos adequados são aplicados -->
<img
  src="/_astro/minha_imagem.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="Uma descrição da minha imagem."
/>

Propriedades

src (obrigatório)

O formato do valor src de sua imagem depende de onde o seu arquivo de imagem está localizado:

Imagens locais em src/ - você deve também importar a imagem utilizando um caminho de arquivo relativo ou configurar e utilizar um atalho de importação. Então, utilize o nome de importação como o valor de src:
src/pages/index.astro
```
---
import { Image } from 'astro:assets';
import minhaImagemImportada from `../assets/minha-imagem-local.png`
---
<Image src={minhaImagemImportada} alt="texto descritivo" />
```

Imagens na pasta public/ - utilize o caminho do arquivo da imagem relativo à pasta public:

---
import { Image } from 'astro:assets';
---
<Image
  src="/imagens/minha-imagem-publica.png"
  alt="texto descritivo"
  width="200"
  height="150"
/>

Imagens remotas - utilize a URL completa da imagem como o valor da propriedade:

---
import { Image } from 'astro:assets';
---
<Image
  src="https://exemplo.com/imagem-remota.jpg"
  alt="texto descritivo"
  width="200"
  height="150"
/>

alt (obrigatório)

Utilize o atributo alt obrigatório para fornecer uma string de texto alternativo descritivo para imagens.

Se uma imagem é meramente decorativa (ou seja, não contribui para o entendimento da página), defina alt="" para que leitores de tela e outras tecnologias assistivas saibam ignorar a imagem.

width e height (obrigatório para imagens em `public/`)

Essas propriedades definem as dimensões a se utilizar para a imagem.

Ao utilizar imagens em sua proporção original, o width e height são opcionais. Essas dimensões podem ser inferidos automaticamente a partir de arquivos de imagem localizados em src/ e a partir de imagens remotas com inferSize definido como true.

No entanto, essas duas propriedades são necessárias para imagens armazenadas em sua pasta public/, pois o Astro não consegue analisar esses arquivos.

densities

Adicionado em: astro@3.3.0

Uma lista de densidades de pixel a serem geradas para a imagem.

Se fornecido, esse valor será usado para gerar um atributo srcset na tag <img>. Não forneça um valor para widths ao usar esse valor.

As densidades que são iguais a larguras maiores do que a imagem original serão ignoradas para evitar o aumento da escala da imagem.

---
import { Image } from 'astro:assets';
import minhaImagem from "../assets/minha_imagem.png";
---
<Image
  src={minhaImagem}
  width={minhaImagem.width / 2}
  densities={[1.5, 2]}
  alt="Uma descrição da minha imagem."
/>

<!-- Resultado -->
<img
  src="/_astro/minha_imagem.hash.webp"
  srcset="
    /_astro/minha_imagem.hash.webp 1.5x
    /_astro/minha_imagem.hash.webp 2x
  "
  alt="Uma descrição da minha imagem."
  width="800"
  height="450"
  loading="lazy"
  decoding="async"
/>

widths

Adicionado em: astro@3.3.0

Uma lista de larguras a serem geradas para a imagem.

Se fornecido, esse valor será usado para gerar um atributo srcset na tag <img>. Uma propriedade sizes também deve ser fornecida.

Não forneça um valor para densities ao usar este valor. Apenas um destes dois valores pode ser usado para gerar um srcset.

Larguras que forem maiores do que a imagem original serão ignoradas para evitar o aumento da escala da da imagem.

---
import { Image } from 'astro:assets';
import minhaImagem from "../assets/minha_imagem.png"; // Image is 1600x900
---
<Image
  src={minhaImagem}
  widths={[240, 540, 720, minhaImagem.width]}
  sizes={`(max-width: 360px) 240px, (max-width: 720px) 540px, (max-width: 1600px) 720px, ${minhaImagem.width}px`}
  alt="Uma descrição da minha imagem."
/>

<!-- Resultado -->
<img
  src="/_astro/minha_imagem.hash.webp"
  srcset="
    /_astro/minha_imagem.hash.webp 240w,
    /_astro/minha_imagem.hash.webp 540w,
    /_astro/minha_imagem.hash.webp 720w,
    /_astro/minha_imagem.hash.webp 1600w
  "
  sizes="
    (max-width: 360px) 240px,
    (max-width: 720px) 540px,
    (max-width: 1600px) 720px,
    1600px
  "
  alt="Uma descrição da minha imagem."
  width="1600"
  height="900"
  loading="lazy"
  decoding="async"
/>

format

Você pode opcionalmente definir um tipo de arquivo de imagem final para ser utilizado.

Por padrão, o componente <Image /> irá produzir um arquivo .webp.

quality

quality é uma propriedade que pode tanto ser:

uma predefinição (low, mid, high, max) que é automaticamente normalizada entre formatos.
um número de 0 a 100 (interpretado diferentemente entre formatos).

inferSize

Adicionado em: astro@4.4.0

Te permite definir os valores originais de width e height de uma imagem remota automaticamente.

Por padrão, essa propriedade é definida como false e você deve especificar ambas as dimensões para sua imagem remota.

Adicione inferSize ao componente <Image /> (ou inferSize: true em getImage()) para inferir esses valores da imagem remota quando baixada. Isso é útil quando você não sabe as dimensões da imagem remota, ou quando elas podem mudar.

---
import { Image } from 'astro:assets';
---
<Image src="https://example.com/cat.png" inferSize alt="Um gato dormindo no sol."/>

inferSize pode obter as informações de uma imagem remota de um domínio que não foi autorizado, no entanto, a imagem em si permanecerá não processada.

Propriedades adicionais

Além das propriedades acima, o componente <Image /> aceita todas as propriedades aceitas pela tag HTML <img>.

Por exemplo, você pode fornecer uma class para o elemento <img> final.

---
import { Image } from 'astro:assets';
import minhaImagem from "../assets/minha_imagem.png";
---

<!-- `alt` é obrigatório no componente Image -->
<Image src={minhaImagem} alt="" class="minha-classe" />

<!-- Resultado -->
<img
  src="/_astro/minha_imagem.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  class="minha-classe"
  alt=""
/>

Definindo Valores Padrões

Atualmente, não há uma forma de especificar valores padrões para todos os componentes <Image />. Atributos obrigatórios devem ser definidos em cada componente individual.

Como uma alternativa, você pode envolver esses componentes em outro componente Astro para reutilização. Por exemplo, você poderia criar um componente para suas imagens de postagens do blog:

---
import { Image } from 'astro:assets';

const {src, ...attrs} = Astro.props;
---
<Image src={src} {...attrs} />

<style>
  img :global(img), svg {
    margin-block: 2.5rem;
    border-radius: 0.75rem;
  }
</style>

`<Picture />`

Adicionado em: astro@3.3.0

Utilize o componente <Picture /> integrado do Astro para exibir uma imagem responsiva com vários formatos e/ou tamanhos.

---
import { Picture } from 'astro:assets';
import minhaImagem from "../assets/minha_imagem.png"; // Image is 1600x900
---

<!-- `alt` é obrigatório no componente Picture -->
<Picture src={minhaImagem} formats={['avif', 'webp']} alt="Uma descrição para a minha imagem." />

<!-- Resultado -->
<picture>
  <source srcset="/_astro/minha_imagem.hash.avif" type="image/avif" />
  <source srcset="/_astro/minha_imagem.hash.webp" type="image/webp" />
  <img
    src="/_astro/minha_imagem.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="Uma descrição da minha imagem."
  />
</picture>

Propriedades

<Picture /> aceita todas as propriedades do componente <Image />, além das seguintes:

`formats`

Um array de formatos de imagem a serem usados para as tags <source>. As entradas serão adicionadas como elementos <source> na ordem em que estão listadas, e essa ordem determina qual formato é exibido. Para obter o melhor desempenho, liste o formato mais moderno primeiro (por exemplo, webp ou avif). Por padrão, isso é configurado como ['webp'].

`fallbackFormat`

Formato a ser usado como um valor de fallback para a tag <img>.

Por padrão, é configurado como .png para imagens estáticas (ou .jpg se a imagem for um JPG), .gif para imagens animadas e .svg para arquivos SVG.

`pictureAttributes`

Um objeto de atributos a serem adicionados à tag <picture>.

Use essa propriedade para aplicar atributos ao elemento externo <picture>. Atributos aplicados diretamente ao componente <Picture /> serão aplicados internamente ao elemento <img>, exceto aqueles usados para transformação de imagens.

---
import { Picture } from "astro:assets";
import minhaImagem from "../minha_imagem.png"; // Imagem é 1600x900
---

<Picture
  src={minhaImagem}
  alt="Uma descrição da minha imagem."
  pictureAttributes={{style: "background-color: red;"}}
/>

<!-- Resultado -->
<picture style="background-color: red;">
  <source srcset="/_astro/minha_imagem.hash.webp" type="image/webp" />
  <img
    src="/_astro/minha_imagem.hash.png"
    alt="Uma descrição da minha imagem."
    width="1600"
    height="900"
    loading="lazy"
    decoding="async"
  />
</picture>

`<img>`

A sintaxe de templates do Astro também suporta escrever uma tag <img> diretamente, com controle total sobre seu resultado final. Essas imagens não serão processadas e otimizadas.

Ela aceita todas as propriedades da tag HTML <img>, e a única propriedade obrigatória é src.

Imagens locais em `src/`

Imagens locais devem ser importadas de seu caminho relativo a partir do arquivo .astro existente, ou configure e utilize um atalho de importação. Então, você pode acessar o src da imagem e outras propriedades para utilizar na tag <img>.

Por exemplo, utilize as propriedades height e width da imagem para evitar CLS e melhorar os Core Web Vitals.

---
// importe imagens locais
import meuCachorro from `../../imagens/pets/cachorro-local.jpg`
---
// acesse as propriedades da imagem
<img src={meuCachorro.src} width={meuCachorro.width} height={meuCachorro.height} alt="Um cachorro latindo." />

Assets de imagem importadas correspondem à seguinte assinatura:

interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}

Imagens em `public/`

Para imagens localizadas em public/ utilize o caminho do arquivo relativo a pasta public da imagem como o valor src:

<img src="/imagens/gato-em-public.jpg" alt="Um gato dormindo.">

Imagens remotas

Para imagens remotas, utilize a URL completa da imagem como o valor de src:

<img src="https://exemplo.com/gato-remoto.jpg" alt="Um gato dormindo.">

Escolhendo `<Image />` vs `<img>`

O componente <Image /> otimiza sua imagem e infere a largura e altura (de imagens locais) com base na proporção original para evitar CLS.

Utilize o elemento <img> do HTML quando você não pode utilizar o componente <Image />, por exemplo:

para formatos de imagem não suportados
quando você não quer que sua imagem seja otimizada pelo Astro
para acessar e modificar o atributo src dinamicamente no lado do cliente

Autorizando imagens remotas

Você pode configurar listas de domínios e padrões de URL fonte de imagens autorizadas para otimização de imagem utilizando image.domains e image.remotePatterns. Essa configuração é uma camada adicional de segurança para proteger seu site ao mostrar imagens de uma fonte externa.

Imagens remotas de outras fontes não serão otimizadas, mas utilizando o componente <Image /> para essas imagens irá prevenir Cumulative Layout Shift (CLS).

Por exemplo, a seguinte configuração irá apenas permitir imagens remotas de astro.build a serem otimizadas:

export default defineConfig({
  image: {
    domains: ["astro.build"],
  }
});

A seguinte configuração irá apenas permitir imagens remotas de hospedagens HTTPS:

export default defineConfig({
  image: {
    remotePatterns: [{ protocol: "https" }],
  }
});

Utilizando Imagens de CMS ou CDN

CDNs de imagem funcionam com todas as opções de imagem do Astro. Utilize a URL completa de uma imagem como o atributo src no componente <Image />, em uma tag <img>, ou na notação do Markdown. Para otimização de imagem com imagens remotas, também configure seus domínios e padrões de URL autorizados.

Alternativamente, se o CDN fornece um SDK para Node.js, você pode utilizá-lo em seu projeto. Por exemplo, o SDK da Cloudinary pode gerar uma tag <img> com o src apropriado para você.

Imagens em arquivos Markdown

Utilize a sintaxe padrão do Markdown ![alt](src) em seus arquivos .md. Essa sintaxe funciona com a API de Serviço de Imagem do Astro para otimizar suas imagens locais e imagens remotas autorizadas.

# Minha Página Markdown

<!-- Imagem local armazenada em src/assets/ -->
<!-- Utilize um caminho de arquivo relativo ou atalho de importação -->
![Uma noite com um céu estrelado.](../assets/estrelas.png)

<!-- Imagem armazenada em public/imagens/ -->
<!-- Utilize o caminho de arquivo relativo ao public/ -->
![Uma noite com um céu estrelado.](/imagens/estrelas.png)

<!-- Imagem remota em outro servidor -->
<!-- Utilize a URL completa da imagem -->
![Astro](https://exemplo.com/imagens/imagem-remota.png)

A tag <img> não é suportada para imagens locais, e o componente <Image /> está indisponível em arquivos .md.

Se você precisa de mais controle sobre seus atributos da imagem, nós recomendamos utilizar o formato de arquivo .mdx, que te permite incluir o componente <Image /> do Astro ou uma tag <img /> JSX em adição a sintaxe do Markdown. Utilize a integração MDX para adicionar suporte para MDX ao Astro.

Imagens em arquivos MDX

Você pode utilizar o componente <Image /> do Astro e tags <img /> JSX em seus arquivos .mdx importando ambos o componente e sua imagem. Utilize-os assim como eles são utilizados em arquivos .astro.

Adicionalmente, há suporte para sintaxe padrão do Markdown ![alt](src) com nenhuma importação necessária.

---
titulo: Título da Minha Página
---
import { Image } from 'astro:assets';
import foguete from '../assets/foguete.png';

# Minha Página MDX

// Imagem local armazenada na mesma pasta
![Houston pelo mundo](houston.png)

// Imagem local armazenada em src/assets/
<Image src={foguete} alt="Um foguete no espaço."/>
<img src={foguete.src} alt="Um foguete no espaço." />
![Um foguete no espaço](../assets/foguete.png)

// Imagens armazenada em public/imagens/
<Image src="/imagens/estrelas.png" alt="Uma noite com um céu estrelado." />
<img src="/imagens/estrelas.png" alt="Uma noite com um céu estrelado." />
![Uma noite com um céu estrelado.](/imagens/estrelas.png)

// Imagem remota em outro servidor
<Image src="https://exemplo.com/imagens/imagem-remota.png" />
<img src="https://exemplo.com/imagens/imagem-remota.png" />
![Astro](https://exemplo.com/imagens/imagem-remota.png)

Imagens em coleções de conteúdo

Imagens em coleções de conteúdo serão processadas da mesma forma que em arquivos Markdown e MDX dependendo do tipo de arquivo que você estiver usando.

Além disso, você pode declarar uma imagem associada a uma entrada de coleções de conteúdo, como a imagem de capa de uma postagem de blog, em seu frontmatter usando seu caminho relativo à pasta atual:

---
title: "Minha primeira postagem do blog"
capa: "./capaprimeirapostagem.jpeg" # será resolvido como "src/content/blog/capaprimeirapostagem.jpeg"
altCapa: "Uma fotografia de um pôr do sol atrás de uma cadeia de montanhas."
---

Essa é uma postagem no blog

O utilitário image para esquemas de coleções de conteúdo te permite validar os metadados da imagem utilizando Zod.

import { defineCollection, z } from "astro:content";

const blogCollection = defineCollection({
  schema: ({ image }) => z.object({
    titulo: z.string(),
    capa: image().refine((img) => img.width >= 1080, {
      mensagem: "Imagem de capa deve ter pelo menos 1080 pixels de largura!",
    }),
    altCapa: z.string(),
  }),
});

export const collections = {
  blog: blogCollection,
};

A imagem será importada e transformada em metadados, te permitindo passá-la como o src para <Image/>, <img>, ou getImage().

O exemplo abaixo mostra a página de índice de um blog que renderiza a foto de capa e o título de cada postagem do blog do esquema acima:

---
import { Image } from "astro:assets";
import { getCollection } from "astro:content";
const todasPostagensBlog = await getCollection("blog");
---

{
  todasPostagensBlog.map((post) => (
    <div>
      <Image src={post.data.capa} alt={post.data.capaAlt} />
      <h2>
        <a href={"/blog/" + post.slug}>{post.data.titulo}</a>
      </h2>
    </div>
  ))
}

Imagens em componentes de frameworks de UI

Ao adicionar imagens em um componente de framework de UI, utilize a sintaxe de imagem própria do framework para renderizar uma imagem (por exemplo, <img /> em JSX e <img> em Svelte).

Imagens locais devem primeiro ser importadas para acessar suas propriedades de imagem como src.

import estrelas from "../assets/estrelas.png"

export default function ImagemReact() {
  return (
    <img src={estrelas.src} alt="Uma noite com um céu estrelado." />
  )
}

<script>
  import estrelas from '../assets/estrelas.png'
</script>

<img src={estrelas.src} alt="Uma noite com um céu estrelado." />

Passando o componente Image

O componente <Image />, assim como qualquer outro componente Astro, não está disponível para componentes de frameworks de UI.

Porém, você pode passar o conteúdo estático gerado por <Image /> para um componente de framework dentro de um arquivo .astro como um filho ou utilizando um <slot/> nomeado:

---
import ComponenteReact from './ComponenteReact.jsx';
import { Image } from "astro:assets"
import estrelas from "~/estrelas/docline.png";
---

<ComponenteReact>
  <Image src={estrelas} alt="Uma noite com um céu estrelado." />
</ComponenteReact>

Gerando imagens com `getImage()`

A função getImage() foi planejada para gerar imagens destinadas a serem usadas em outro lugar do que diretamente no HTML, por exemplo em uma Rota de API. Ela te permite criar seu próprio componente <Image /> customizado.

Receita relacionada: Build a custom image component (EN)

getImage() recebe um objeto de opções com as mesmas propriedades que o componente Image (exceto alt).

---
import { getImage } from "astro:assets";
import meuPlanoFundo from "../planoFundo.png"

const planoFundoOtimizado = await getImage({src: meuPlanoFundo, format: 'webp'})
---

<div style={`background-image: url(${planoFundoOtimizado.src});`}></div>

Retorna um objeto com as seguintes propriedades:

{
  rawOptions: {...} // Parâmetros originais passados
  options: {...}, // Parâmetros validados passados
  src: "https//..." // Caminho para a imagem gerada
  srcSet: {
    values: [...], // Valores gerados para srcset, cada entrada tem uma url e uma descrição de tamanho
    attribute: "", // Atributo srcset gerado a partir dos valores
  }
  attributes: {...} // Atributos HTML adicionais necessários para renderizar a imagem (width, height, style, etc..)
}

Texto Alternativo

Nem todos os usuários podem ver imagens da mesma forma, então acessibilidade é uma preocupação especialmente importante ao utilizar imagens. Utilize o atributo alt para fornecer texto alternativo descritivo para imagens.

Esse atributo é necessário para ambos os componentes <Image /> e <Picture />. Se nenhum texto alternativo for fornecido, uma mensagem de erro será exibida te lembrando de incluir o atributo alt.

Se a imagem for meramente decorativa (ou seja, não contribui para o entendimento da página), defina alt="" para que leitores de tela saibam ignorar a imagem.

Serviço de imagem padrão

Sharp é o serviço de imagem padrão utilizado em astro:assets. Você pode configurar o serviço de imagem utilizando a opção image.service.

Configure o Squoosh

Se você preferir utilizar Squoosh para transformar suas imagens, atualize sua configuração com o seguinte:

import { defineConfig, squooshImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: squooshImageService(),
  },
});

Configure o serviço de passagem não-operacional

Se o seu adaptador para modo server ou hybrid não suportar os serviços de otimização Squoosh e Sharp integrados do Astro (por exemplo, Deno e Cloudflare), você pode configurar um serviço de imagem não-operacional para permitir que utilize os componentes <Image /> e <Picture />. Note que o Astro não executa nenhuma transformação e processamento de imagens nesses ambientes. No entanto, você ainda pode aproveitar os outros benefícios de utilizar o astro:assets, incluindo não ter Cumulative Layout Shift (CLS), a exigência do atributo alt e uma experiência de criação consistente.

Configure o passthroughImageService para evitar ambos os processamentos de imagem Squoosh e Sharp:

import { defineConfig, passthroughImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: passthroughImageService()
  }
});

Integrações da Comunidade

Há diversas integrações de imagem da comunidade de terceiros para otimizar e trabalhar com imagens em seu projeto Astro.

Atualize para v3.0 da v2.x

astro:assets não está mais atrás de uma flag experimental no Astro v3.0.

<Image /> agora é um componente integrado e a integração @astrojs/image anterior foi removida.

Essas e outras alterações que acompanham o uso de imagens no Astro podem causar algumas mudanças significativas quando você atualizar seu projeto Astro de uma versão anterior.

Por favor siga as instruções abaixo apropriadamente para atualizar um projeto Astro v2.x para v3.0.

Atualize de `experimental.assets`

Se você anteriormente habilitou a flag experimental para astro:assets, você vai precisar atualizar seu projeto para Astro v3.0 que agora inclui funcionalidades de assets por padrão.

Remova a flag `experimental.assets`

Remova a flag experimental:

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
   assets: true
  }
});

Se necessário, também atualize seu arquivo src/env.d.ts para substituir a referência astro/client-image com astro/client:

/// <reference types="astro/client-image" />
/// <reference types="astro/client" />

Remova o atalho de importação `~/assets`

Esse atalho de importação não é mais incluído por padrão com astro:assets. Se você estava utilizando esse atalho com assets experimentais, você deve convertê-los em caminhos de arquivo relativos ou criar seu próprio atalho de importação.

---
import foguete from '~/assets/foguete.png'
import foguete from '../../assets/foguete.png';
---

Adicione suporte simples de assets para Cloudflare, Deno, Vercel Edge e Netlify Edge

Astro v3.0 permite que astro:assets funcione sem erros no Cloudflare, Deno, Vercel Edge e Netlify Edge, que não suportam a otimização de imagem Squoosh e Sharp integrada do Astro. Observe que o Astro não realiza nenhuma transformação e processamento de imagem nesses ambientes. No entanto, você ainda pode aproveitar os outros benefícios do uso de astro:assets, incluindo a ausência de Cumulative Layout Shift (CLS), o atributo alt obrigatório e uma experiência de criação consistente.

Se antes você evitava usar astro:assets por causa dessas restrições, agora pode usá-los sem problemas. Você pode configurar o serviço de imagem no-op para aceitar explicitamente esse comportamento:

import { defineConfig } from 'astro/config';

export default defineConfig({
  image: {
    service: {
      entrypoint: 'astro/assets/services/noop'
    }
  }
});

Decida onde armazenar suas imagens

Veja o guia de Imagens para te ajudar a decidir onde armazenar suas imagens. Você pode desejar se aproveitar de novas opções para armazenar suas imagens com a flexibilidade adicional que astro:assets traz. Por exemplo, imagens relativas a partir do src/ do seu projeto podem ser referenciadas em Markdown, MDX e Markdoc utilizando a sintaxe padrão do Markdown ![alt](src).

Atualize tags `<img>` existentes

Anteriormente, a importação de uma imagem retornava uma simples string com o caminho da imagem. Agora, os assets de imagem importados correspondem à seguinte assinatura:

interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}

Você deve atualizar o atributo src de quaisquer tags <img> existentes (incluindo quaisquer imagens em componentes de framework de UI) e você também pode atualizar outros atributos que agora estão disponíveis para você da imagem importada.

---
import foguete from '../imagens/foguete.svg';
---
<img src={foguete} width="250" height="250" alt="Um foguete no espaço." />

<img src={foguete.src} width={foguete.width} height={foguete.height} alt="Um foguete no espaço." />

Atualize seus arquivos Markdown, MDX e Markdoc

Imagens relativas da pasta src/ do seu projeto agora podem ser referenciadas em Markdown, MDX e Markdoc utilizando a sintaxe padrão do Markdown ![alt](src).

Isso te permite mover suas imagens do diretório public/ para o src/ do seu projeto onde agora elas serão processadas e otimizadas. Suas imagens existentes em public/ e imagens remotas ainda são válidas mas não são otimizadas pelo processo de build do Astro.

# Minha Página Markdown

<!-- Imagens locais agora são possíveis! -->
![Uma noite com um céu estrelado.](../../imagens/estrelas.png)

<!-- Mantenha suas imagens próximas do seu conteúdo! -->
![Uma noite com um céu estrelado.](./estrelas.png)

Se você requer mais controle sobre seus atributos de imagem, nós recomendamos utilizar o formato de arquivo .mdx, que permite incluir o componente <Image /> do Astro ou uma tag JSX <img /> além da sintaxe do Markdown. Utilize a integração MDX para adicionar suporte de MDX ao Astro.

Remova `@astrojs/image`

Se você estava utilizando a integração de imagem em Astro v2.x, complete as seguintes etapas:

Remova a integração @astrojs/image.

Você deve remover a integração desinstalando-a e, em seguida, removendo-a do seu arquivo astro.config.mjs.

import { defineConfig } from 'astro/config';
import image from '@astrojs/image';

export default defineConfig({
  integrations: [
    image(),
  ]
})

Atualize tipos (se necessário).

Se você tinha tipos especiais configurados para @astrojs/image em src/env.d.ts, pode ser necessário alterá-los de volta para os tipos padrão do Astro se a atualização para a versão 3 não concluiu esta etapa automaticamente para você.
src/env.d.ts
```
 /// <reference types="@astrojs/image/client" />
 /// <reference types="astro/client" />
```
Da mesma forma, atualize o tsconfig.json se necessário:
tsconfig.json
```
{
  "compilerOptions": {
    "types": ["@astrojs/image/client"]
    "types": ["astro/client"]
  }
}
```
Migre quaisquer componentes <Image />.

Modifique todas as declarações import de @astrojs/image/components para astro:assets para utilizar o novo componente <Image /> integrado.

Remova quaisquer atributos do componente que não são propriedades de asset de imagem atualmente suportadas.

Por exemplo, aspectRatio não é mais suportado, já que agora é automaticamente inferido dos atributos width e height.
src/components/MeuComponente.astro
```
---
import { Image } from '@astrojs/image/components';
import { Image } from 'astro:assets'
import imagemLocal from "../assets/logo.png";
const altLocal = "A logo do Astro";
---

<Image
  src={imagemLocal}
  width={300}
  aspectRatio="16:9"
  alt={altLocal}
/>
```
Escolha o serviço de imagem padrão.

Sharp agora é o serviço de imagem padrão usado para astro:assets. Se você quiser utilizar Sharp, nenhuma configuração é necessária.

Se você preferir utilizar Squoosh para transformar suas imagens, atualize sua configuração com a opção image.service a seguir:
astro.config.mjs
```
import { defineConfig, squooshImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: squooshImageService(),
  },
});
```

Atualize esquemas de Coleções de Conteúdo

Agora você pode declarar uma imagem associada a uma entrada de coleções de conteúdo, como a imagem de capa de uma postagem de blog, em seu frontmatter usando seu caminho relativo à pasta atual.

O novo utilitário image para coleções de conteúdo te permite validar os metadados da imagem utilizando Zod. Aprenda mais sobre como utilizar imagens em coleções de conteúdo.

Navegando Importações de Imagem no Astro v3.0

No Astro v3.0, se você precisar preservar o antigo comportamento de importação para imagens e exigir uma representação de string do URL da imagem, adicione ?url ao final do caminho da sua imagem ao importá-la. Por exemplo:

---
import Sprite from '../assets/logo.svg?url';
---

<svg>
  <use xlink:href={Sprite + '#carrinho'} />
</svg>

Essa abordagem garante que você obtenha a string de URL. Tenha em mente que, durante o desenvolvimento, o Astro usa um caminho src/, mas, ao fazer build, ele gera caminhos com hash como /_astro/gato.a6737dd3.png.

Se você preferir trabalhar diretamente com o próprio objeto de imagem, você pode acessar a propriedade .src. Essa abordagem é melhor para tarefas como gerenciar as dimensões da imagem para métricas Core Web Vitals e prevenir o CLS.

Se você estiver em transição para o novo comportamento de importação, combinar os métodos ?url e .src pode ser o método certo para o manuseio de imagens ininterrupto.

Imagens

Onde armazenar imagens

src/ vs public/

Imagens remotas

Imagens em arquivos .astro

<Image /> (astro:assets)

Propriedades

src (obrigatório)

alt (obrigatório)

width e height (obrigatório para imagens em public/)

densities

widths

format

quality

inferSize

Propriedades adicionais

Definindo Valores Padrões

<Picture />

Propriedades

formats

fallbackFormat

pictureAttributes

<img>

Imagens locais em src/

Imagens em public/

Imagens remotas

Escolhendo <Image /> vs <img>

Autorizando imagens remotas

Utilizando Imagens de CMS ou CDN

Imagens em arquivos Markdown

Imagens em arquivos MDX

Imagens em coleções de conteúdo

Imagens em componentes de frameworks de UI

Passando o componente Image

Gerando imagens com getImage()

Texto Alternativo

Serviço de imagem padrão

Configure o Squoosh

Configure o serviço de passagem não-operacional

Integrações da Comunidade

Atualize para v3.0 da v2.x

Atualize de experimental.assets

Remova a flag experimental.assets

Remova o atalho de importação ~/assets

Adicione suporte simples de assets para Cloudflare, Deno, Vercel Edge e Netlify Edge

Decida onde armazenar suas imagens

Atualize tags <img> existentes

Atualize seus arquivos Markdown, MDX e Markdoc

Remova @astrojs/image

Atualize esquemas de Coleções de Conteúdo

Navegando Importações de Imagem no Astro v3.0

`src/` vs `public/`

Imagens em arquivos `.astro`

`<Image />` (`astro:assets`)

width e height (obrigatório para imagens em `public/`)

`<Picture />`

`formats`

`fallbackFormat`

`pictureAttributes`

`<img>`

Imagens locais em `src/`

Imagens em `public/`

Escolhendo `<Image />` vs `<img>`

Gerando imagens com `getImage()`

Atualize de `experimental.assets`

Remova a flag `experimental.assets`

Remova o atalho de importação `~/assets`

Atualize tags `<img>` existentes

Remova `@astrojs/image`