Building the Photo Stream

The photo stream of my old Astro site: JSON sidecars next to each JPG, import.meta.glob, a justified grid and batches revealed on scroll.

I wanted a photo section on my old site without a CMS, a media server or data fetched in the browser. JPG files on disk, everything else resolved at build time. This guide was the first of a series on the photo section; the later parts are albums, a collection tree, sets and category nodes and why the tree left the content layer.

The setup

  • Site: a static Astro 6 build, deployed as a single container.
  • Source: JPG files plus JSON sidecars in src/content/photos/albums/.
  • Goal: a chronological stream of photos in a justified grid, loaded in batches on scroll, with no backend at runtime.

Sidecar files

Each photo has a .json file with the same base name:

img/
  2025-10-06-121017.jpg
  2025-10-06-121017.json

The script scripts/vision.ts generated it: a vision model wrote the alt text and title (OpenAI at the time of the post), and exiftool read the EXIF data. The script has its own page.

{
  "id": "2025-10-06-121017",
  "title": ["Golden Temple Bell in Sunlit Foliage", ...],
  "alt": "A small brass bell hangs from a leafy branch...",
  "location": "18 deg 48' 16.92\" N, 98 deg 55' 18.92\" E",
  "date": "2025-10-06",
  "tags": ["bell", "brass", "leaves", "bokeh"],
  "exif": {
    "camera": "X-T3",
    "lens": "XF16-55mmF2.8 R LM WR",
    "aperture": "2.8",
    "iso": "400",
    "focal_length": "55.0",
    "shutter_speed": "1/250"
  }
}

A sibling file keeps the metadata out of the content collections and out of the image files. The build reads whatever JSON files lie next to the images. No registration step, no indexer.

Pairing images with sidecars

The build has to match each sidecar with its JPG, run the images through Astro's image pipeline and sort everything by date, without a database. Both file types load with import.meta.glob, and Vite resolves the paths at build time:

const sidecars = import.meta.glob<PhotoSidecar>(
  "/src/content/photos/albums/**/*.json",
  { eager: true },
);

const imageModules = import.meta.glob<{ default: ImageMetadata }>(
  "/src/content/photos/albums/**/*.jpg",
  { eager: true },
);

Pairing is a plain path replacement:

const photos = Object.entries(sidecars)
  .map(([jsonPath, sidecar]) => {
    const imgPath = jsonPath.replace(".json", ".jpg");
    const image = imageModules[imgPath]?.default;
    return { sidecar, image };
  })
  .filter((p) => !!p.image)
  .sort((a, b) =>
    new Date(b.sidecar.date).getTime() - new Date(a.sidecar.date).getTime(),
  );

A sidecar without a matching JPG is dropped, and the stream is sorted newest first by the sidecar's date. With eager: true Vite puts all resolved modules into the build. Astro's <Image> component handles resizing, format conversion and the srcset for each photo.

Justified layout

The grid used justified-layout, the library Flickr uses. It computes rows in which every image has the same height and each row fills the container width:

import justifiedLayout from "justified-layout";

const result = justifiedLayout(ratios, {
  containerWidth: grid.offsetWidth,
  targetRowHeight: 280,
  boxSpacing: 8,
  containerPadding: 0,
});

ratios holds width / height for each visible photo. The result gives top, left, width and height for every box. The grid container gets position: relative and the computed containerHeight, and each item is positioned absolutely. On screens up to 640px the script is skipped: the grid becomes a plain flex column with the photos' natural aspect ratios.

Batch loading with IntersectionObserver

Every photo is in the HTML from the build, but everything after the first batch is hidden:

<div
  class="photo-item"
  data-ar={ar}
  data-batch={Math.floor(i / BATCH_SIZE)}
  data-hidden={i >= BATCH_SIZE ? "true" : undefined}
>

BATCH_SIZE is 15. A sentinel element sits below the grid, and an IntersectionObserver watches it with a 400px root margin. When the reader nears the bottom, the next batch appears and the layout is recalculated:

const observer = new IntersectionObserver(
  (entries) => {
    if (entries[0]?.isIntersecting) revealNextBatch();
  },
  { rootMargin: "400px" },
);
observer.observe(sentinel);

That replaces a paginated API. All image URLs are already in the HTML, and the lazy loading of <Image> fetches them as they come into view.

A page per photo

Each photo gets a static page at /photos/[id], generated from the same sidecar list:

export async function getStaticPaths() {
  return photos.map((photo) => ({
    params: { id: photo.sidecar.id },
    props: { sidecar: photo.sidecar, image: photo.image },
  }));
}

The page shows the full image, title, date, EXIF data and tags. Previous and next are computed in the page body, not in getStaticPaths, to avoid problems with serialising the sorted array as props:

const sortedIds = Object.values(allSidecars)
  .sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime())
  .map((s) => s.id);

const currentIndex = sortedIds.indexOf(sidecar.id);
const prevId = sortedIds[currentIndex - 1] ?? null;
const nextId = sortedIds[currentIndex + 1] ?? null;

Takeaways

  • A JSON sidecar next to each JPG is enough metadata storage for a static photo stream; no content collection needed.
  • import.meta.glob with { eager: true } is the right tool for pairing files at build time in Vite and Astro.
  • Turn the justified layout off on mobile instead of fighting it.
  • Rendering every item at build time and revealing batches with IntersectionObserver replaces pagination with almost no runtime code.

More on this

Topic
  • Static Website A website made of finished HTML files that are built once and then served unchanged. No server code, no database.
Basis for
Uses
  • Astro Tool for building websites from content such as Markdown. Ships plain HTML by default and only loads JavaScript where it is needed.
Mentioned in
  • Syndicating Photos to Flickr A script that makes Flickr match the photo tree of my old site: upload, delete, move between albums, and write the Flickr ID and stats back into the sidecars.
Mentioned

Show in the graph view →