Image & SEO

# image(opts) — responsive images

Emits responsive <img> or <picture> tags with srcset, sizes, lazy loading, and CLS-preventing width/height:

import { image } from "@elurjs/kit";
import { html } from "@elurjs/core";

export default function HeroPage() {
  return html`
    ${image({
      src: "/images/hero.jpg",
      alt: "Hero image",
      width: 1920,
      height: 1080,
      widths: [640, 1280, 1920],
      sizes: "100vw",
      priority: true,
    })}
  `;
}

# ImageOptions

# Build-time processing

When sharp is installed (optional peer dep), build() automatically:

• Generates WebP and AVIF variants at requested widths
• Content-based hashing for indefinite caching
• Emits <picture> with <source> per format
• Uses real dimensions from the manifest

Without sharp, emits a plain <img> with the original src.

# Image pipeline hardening

• SHA-256 transform keys — variant hash incorporates source content digest + transform options + encoder versions
• Path containment — sources and outputs validated against traversal, NUL, symlink escape
• Atomic writes + single-flight — temp+rename with bounded concurrency pool
• images.strict — fails build on missing source or failed transform

# Pipeline limitations

• Local sources only — no remote image fetching (capabilities.remote = false).
• No runtime image endpoint — variants are generated at build time, not on request (capabilities.runtimeEndpoint = false).
• Resize only — no enlargement, crop, or rotation. (ImageRequest.fit exists in the type but is not implemented yet.)
• Manual width/height required — intrinsic dimensions are not detected at render time.
• processImages is the legacy pipeline (pipeline.ts: MD5 keys, non-atomic). processImageBatch / getImage (service.ts) is the hardened path the build uses.

# getImage(request, options) — programmatic

import { getImage } from "@elurjs/kit/image";

const meta = await getImage(
  {
    src: "/images/hero.jpg",
    alt: "Hero",
    widths: [640, 1280],
    formats: ["avif", "webp"],
    width: 1920,
    height: 1080,
    priority: true,
  },
  { publicDir: "public", outDir: "dist" },
);
// meta.src, meta.width, meta.height, meta.sources, meta.attributes, meta.generated

# ImageRequest

# ImageMetadata

# ProcessOptions

Options for getImage and createImageService:

# createImageService(options)

import { createImageService } from "@elurjs/kit/image";

const service = createImageService({ publicDir: "public", outDir: "dist" });
// service.resolve(request, ctx) — resolve an image request
// service.capabilities — ImageServiceCapabilities

# processImages(images, options) — build-time

Processes a batch of images: for each image, generates variants at the specified widths and formats using sharp:

import { processImages } from "@elurjs/kit";

const results = await processImages(
  [
    { src: "/images/hero.jpg", widths: [640, 1280, 1920], formats: ["avif", "webp"] },
    { src: "/images/logo.png", widths: [320, 640], formats: ["webp"] },
  ],
  {
    publicDir: "public",
    outDir: "dist",
    quality: 80,
  }
);
// Returns ProcessedImage[] with src and generated variants

If sharp is not installed, returns an empty array and logs a warning.

# PipelineOptions

# isSharpAvailable()

import { isSharpAvailable } from "@elurjs/kit";

if (isSharpAvailable()) {
  // sharp is installed — build will generate variants
} else {
  // no sharp — images emit plain <img> with original src
}

# consumeImageRegistry()

Returns all images registered via image() during rendering, for build-time processing:

import { consumeImageRegistry } from "@elurjs/kit";

const images = consumeImageRegistry();
// [{ src: "/images/hero.jpg", widths: [640, 1280, 1920] }, ...]

# setImageManifest(manifest)

Loads the image manifest so image() emits <picture> with real variant URLs:

import { setImageManifest } from "@elurjs/kit";

const manifest = JSON.parse(await readFile("dist/_elur/image-manifest.json", "utf-8"));
setImageManifest(manifest);

# ImageManifest

interface ImageManifest {
  entries: Record<string, ImageEntry>;
}

# ImageEntry

# ImageVariant

# SEO

# generateSitemap(config)

Writes sitemap.xml to outDir and returns the file path:

import { generateSitemap } from "@elurjs/kit/seo";

const filePath = await generateSitemap({
  siteUrl: "https://example.com",
  outDir: "./dist",
  urls: [
    "/",
    "/blog",
    { url: "/blog/hello-world", lastmod: "2024-01-15", priority: 0.8 },
  ],
});

# SitemapConfig

# SitemapEntry

# generateRobots(config)

Writes robots.txt to outDir and returns the file path:

import { generateRobots } from "@elurjs/kit/seo";

const filePath = await generateRobots({
  siteUrl: "https://example.com",
  outDir: "./dist",
  disallow: ["/api/", "/_elur/"],
});

# RobotsConfig

# RobotsRule

# jsonLd(schema) — structured data

import { jsonLd } from "@elurjs/kit/seo";

const script = jsonLd({
  "@context": "https://schema.org",
  "@type": "Article",
  headline: "Hello World",
  author: { "@type": "Person", name: "Ada" },
  datePublished: "2024-01-15",
});
// Returns <script type="application/ld+json">...</script>

Safe escaping: <, >, &, U+2028, U+2029 are escaped to prevent injection.

# generateSitemapFromRoutes(options) — automatic sitemap

When site is set in defineConfig, elur-kit build writes sitemap.xml from the scanned route manifest automatically — dynamic routes, error pages, and internal namespaces are excluded; sites over 50,000 URLs are split into sitemap-N.xml files with a sitemap.xml index. An existing sitemap.xml (from public/ or an integration hook) always takes precedence and is never overwritten.

To generate it manually from the scanned routes:

import { generateSitemapFromRoutes } from "@elurjs/kit/seo";

await generateSitemapFromRoutes({
  siteUrl: "https://example.com",
  outDir: "./dist",
  routes,                    // ScannedRoutes from scanRoutes()
  extraUrls: ["/blog/hello-world"], // concrete URLs for dynamic routes
  defaultChangefreq: "weekly",
  defaultPriority: 0.7,
});

Dynamic routes are excluded automatically — pass their concrete URLs via extraUrls (e.g. generated from your content collections).

# Using in build hook

Generate sitemap and robots during build — integration hooks are declared flat on the integration object:

// elur.config.ts
import { defineConfig } from "@elurjs/kit";
import { generateSitemap, generateRobots } from "@elurjs/kit/seo";

export default defineConfig({
  site: "https://example.com",
  integrations: [
    {
      name: "seo",
      build: async (result, ctx) => {
        await generateSitemap({
          siteUrl: "https://example.com",
          outDir: result.outDir,
          urls: ["/", "/blog"],
        });

        await generateRobots({
          siteUrl: "https://example.com",
          outDir: result.outDir,
          disallow: ["/api/"],
        });
      },
    },
  ],
});