Gatsby 3 tiene un cambio importante: toda la sintaxis relacionada con imágenes ha cambiado. Si un proyecto existente se actualiza a Gatsby 3 sin actualizar la sintaxis de imágenes, podría funcionar bien, o podría romperse, o mostrar algunos errores. Como mi proyecto tenía algunos errores extraños, decidí actualizar la sintaxis de imágenes de mi blog. Esto es lo que llaman “más vale prevenir que lamentar”, ¿verdad?

Actualización de plugins

Gatsby 2 usaba gatsby-image para los plugins de imágenes. Al actualizar, primero puedes eliminarlo y cambiar a gatsby-plugin-image, junto con la actualización de plugins relacionados con imágenes:

    npm uninstall gatsby-image
    npm install gatsby-plugin-image gatsby-plugin-sharp gatsby-transformer-sharp

En Gatsby 2, ya sean imágenes estáticas o dinámicas, importarías el componente Img desde import Img from 'gatsby-image' en la parte superior del archivo para configurar las imágenes.

Gatsby 3 cambia esto: las imágenes estáticas importan import { StaticImage } from "gatsby-plugin-image", y las imágenes dinámicas importan import { GatsbyImage } from "gatsby-plugin-image".

Ventajas

¿Por qué actualizar a Gatsby 3? ¿Por qué Gatsby 3 requiere nueva sintaxis para imágenes? Personalmente creo que la nueva sintaxis tiene dos ventajas:

1. En Gatsby 2, todas las imágenes estáticas necesitaban ser proporcionadas a través de GraphQL. La nueva sintaxis de Gatsby 3 usa el componente StaticImage, que te permite poner una URL o ruta relativa directamente en la propiedad, lo cual es de hecho mucho más conveniente.
2. En Gatsby 2, las imágenes dinámicas requerían configurar algunas opciones tanto en GraphQL como en las propiedades del componente. Ahora solo necesitas configurarlas en GraphQL, lo que hace que la sintaxis sea un poco más limpia.

Imágenes estáticas

Al actualizar imágenes estáticas, necesitas prestar atención a los siguientes puntos:

1. Las imágenes estáticas <StaticImage /> ya no necesitan obtener datos de GraphQL.
2. Usar un componente como <StaticImage src="trex.png" width={width} height={width/2} /> es casi igual que el <img /> de HTML.
3. <StaticImage /> todavía disfruta de la carga diferida de Gatsby, generación automática de imágenes de tamaño apropiado y otras características.
4. Si los archivos remotos cambian, no se actualizarán automáticamente de inmediato; se actualizarán después de una reconstrucción.
5. En la documentación de Gatsby, para la sección de opciones, elige las partes de cadena, no el enum.
6. Los props de <StaticImage /> no pueden pasarse desde otros archivos, funciones o componentes.

Mis imágenes provienen de un CMS y a menudo se pasan a través de propiedades, por lo que en realidad no uso <StaticImage /> muy a menudo; uso más <GatsbyImage />.

Imágenes dinámicas

La sintaxis para imágenes dinámicas ha cambiado bastante. Un punto importante es la sintaxis en GraphQL:

    fixed {
        ...GatsbyImageSharpFixed
    }

Cambiado a:

    gatsbyImageData(layout: FIXED)

O:

    gatsbyImageData(
        width: 200
        placeholder: BLURRED
        formats: [AUTO, WEBP, AVIF]
    )

La sintaxis del componente se convierte en: <GatsbyImage image={data.file.childImageSharp.gatsbyImageData} />

Podemos observar que las opciones que estaban en el componente en Gatsby 2 se han movido todas a GraphQL. En Gatsby 3, el componente no necesita configurar ninguna propiedad.

Ten en cuenta que la documentación oficial de Gatsby enumera los valores de opción: usa valores enum en mayúsculas para GraphQL, minúsculas para las propiedades del componente.

Otros métodos

getImage()

Para usar este método, puedes importarlo en la parte superior del archivo: import { getImage } from 'gatsby-plugin-image'. La función principal de este método es que data.file.childImageSharp.gatsbyImageData en <GatsbyImage image={data.file.childImageSharp.gatsbyImageData} /> puede reemplazarse con getImage(data.file.childImageSharp).

Usando esta sintaxis, si el valor de gatsbyImageData es null, getImage() devolverá undefined en lugar de romper toda la aplicación. Es esencialmente lo mismo que la sintaxis childImageSharp?.gatsbyImageData, por lo que no tienes que usar getImage() si no quieres.

getSrc()

Similar a getImage(), principalmente se usa cuando no necesitas las funciones de procesamiento de imágenes de Gatsby y solo necesitas obtener la URL de la imagen directamente, para componentes como SEO. El propósito también es prevenir errores null.

    import { getSrc } from "gatsby-plugin-image"
    const HomePage = ({ data }) => {
        const imagePath = getSrc(data.file)
        return (
            <>
                <SEO imageSrc={imagePath} />
            </>
        )
    }

Ejemplos

Puedes hacer clic en “Antes” y “Después” para ver los archivos originales:

Antes:

            images {
              fluid {
                ...GatsbyContentfulFluid
              }

Después:

    images {
        gatsbyImageData(
            width: 800
            placeholder: BLURRED
            aspectRatio:1.5
        )
    }

Antes:

    <TagCard
        slug={slug.toLowerCase()}
        key={`tag-${slug.toLowerCase()}`}
        iceFireNumber={iceFireNumber}
        postTitle={title}
        publishedDate={publishedDate}
        excerpt={excerpt}
        timeToRead={(timeToRead * 1.5)}
        imageSrc={element.images[0].fluid}
    />

Después:

    const image = getImage(element.images[0]);
    return (
    <TagCard
        slug={slug.toLowerCase()}
        key={`tag-${slug.toLowerCase()}`}
        iceFireNumber={iceFireNumber}
        postTitle={title}
        publishedDate={publishedDate}
        excerpt={excerpt}
        timeToRead={(timeToRead * 1.5)}
        image={image}
    />

Antes:

    import Img from 'gatsby-image'

Después:

    import { GatsbyImage } from 'gatsby-plugin-image'

Antes:

    <Link to={`/blog/${slug}/`}>
        <Img className="db" fluid={{ ...imageSrc, aspectRatio: 1.5 }} />
    </Link>

Después:

    <Link to={`/blog/${slug}/`}>
        <GatsbyImage className="db" image={image} alt={postTitle} />
    </Link>

Cómo leer documentación

Para pasos detallados de actualización, consulta la documentación oficial de alta calidad. Lo anterior es solo mi resumen y agregados de lo que creo que son los puntos más importantes. A continuación, compartiré algunas ideas de esta experiencia de actualización.

Como desarrollador de Gatsby, inevitablemente necesitas leer la documentación de Gatsby con frecuencia. De hecho, la calidad de la documentación de Gatsby es excelente, sin mencionar el código de ejemplo útil, y algunos lugares incluso incluyen tutoriales en video. A pesar de esto, siempre sentí que leer la documentación de Gatsby tomaba mucho tiempo.

Mi forma anterior de leer documentación era leer mientras hacía: primero entender la documentación, luego seguir paso a paso, saltando a otra documentación o buscando información en Google entre medio, luego escribir código para implementar, luego volver a la documentación para continuar la implementación, y finalmente tomar notas después de implementar con éxito.

Este proceso tenía un pequeño inconveniente: cuando volvía a revisar la documentación a mitad de camino, me parecía que llevaba mucho tiempo por las siguientes razones:

1. La documentación está en inglés, que siempre es más lenta de leer que el español.
2. La documentación es demasiado detallada y cubre varias situaciones, pero yo podría solo necesitar 2-3 escenarios.
3. La lógica de organización de la documentación no necesariamente coincide con mi lógica de búsqueda.

Entonces, para esta actualización a Gatsby 3, hice un pequeño cambio: leí la documentación primero sin escribir código, extrayendo directamente las partes que pensaba que usaría para crear notas, esencialmente creando mi propia versión de la documentación. Luego, cuando comencé a escribir código, seguí mi propia versión de la documentación.

Descubrí que este pequeño cambio redujo significativamente el tiempo que pasaba leyendo documentación, porque estaba leyendo mi propia versión en español de la documentación, que solo documentaba los 2-3 escenarios que usaría. Más importante aún, esta documentación personalizada seguía mi propia lógica para recordar y buscar, por lo que podía encontrar cosas muy rápidamente con mis ojos.

Hay un pequeño problema: como no estaba implementando mientras leía la documentación, ocasionalmente malinterpretaba la documentación original. Eso está bien: cuando descubras esta situación, solo modifica tu propia versión de la documentación. Y cuando la actualización esté completa, organizar las notas será mucho más rápido.

Para esta actualización a Gatsby 3, este método de leer documentación fue en realidad mi mayor aprendizaje.