Guides

Astro.js

Gumlet Image Integration for Astro.js

Easily optimize and deliver images in your Astro app using Gumlet’s CDN and JS SDK. This guide explains setup, usage, and advanced options in a reusable component format.

Installation & Setup

  1. Create a Gumlet Astro Component

Create src/components/GumletImage.astro:

---
// GumletImage.astro
const { src, alt = "", style = "", ...rest } = Astro.props;
---
<img
  data-src={src}
  alt={alt}
  style={style}
  {...rest}
/>
  1. Load Gumlet JS and Configure in Global Layout

Add to your main layout (e.g., src/layouts/BaseLayout.astro):

<head>
  <!-- Gumlet Configuration -->
  <script>
    window.GUMLET_CONFIG = {
      hosts: [
        {
          current: "example.com",      // Your site’s domain
          gumlet: "mysubdomain.gumlet.io" // Your Gumlet source
        }
      ],
      lazy_load: true
    };
  </script>
  <script
    src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gumlet.min.js"
    id="gumlet-sdk-script"
    sync
  ></script>
</head>

Replace "example.com" and "mysubdomain.gumlet.io" with your actual domain and Gumlet subdomain.

Usage

Import and use the Gumlet image component in your Astro pages:

---
import GumletImage from '../components/GumletImage.astro';
---
<GumletImage
  src="https://yourdomain.com/images/photo.jpg"
  alt="Alt text for SEO"
  style="width: 400px;"
/>
  • Use data-src instead of src for automatic Gumlet processing.
  • Works with lazy loading and responsive images.

Image Transformations

Pass additional Gumlet parameters inside src URL:

<GumletImage
  src="https://yourdomain.com/images/photo.jpg?w=400&format=webp"
  alt="Optimized"
  style="width: 400px;"
/>

See Gumlet API Docs for available options.

Advanced

  • Use any HTML img attribute as a prop.
  • SSR support: Output is standard HTML <img> tags.
  • For Astro static builds, images remain optimized via Gumlet CDN.

Example

<GumletImage
  src="https://demo.gumlet.io/logo.png?w=300"
  alt="Company logo"
  style="width:300px;"
/>

Troubleshooting

  • Double-check your Gumlet source/domain config.
  • Always use data-src (not src).
  • Gumlet JS must load before images are rendered.