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.globwith{ 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
IntersectionObserverreplaces pagination with almost no runtime code.
- 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
-
- Photo Albums with Astro's Content Layer Album pages on top of the photo stream of my old site: a content collection per album, covers by filename, album-scoped photo routes and a sub-nav.
- 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
-
- Collection Sets and Category Collections One boolean in the frontmatter told the photo sets of my old site apart from pure navigation nodes, so only finished sets reached the archive.
- Photo Sidecars with a Vision Model The script vision.ts of my old site: EXIF data and a vision model's alt text, titles and tags in a JSON file next to each photo, generated locally before the deploy.
- Structuring Photos as a Collection Tree How the photos of my old Astro site grew from flat albums into a recursive tree: one catch-all route, photos per node, breadcrumbs and tag pages.
- Why the Photo Tree Is No Content Collection Anymore When my old Astro site went bilingual, the photo tree left the content layer: every photo and node needs both languages in one file.
- Tags