Vibe coding with Claude Code course ยท Module 4: Instagram clone
Treasure Chest Photos: the Image Component from Next.js
In this lesson11
Ahoy! A new location means a new clone: Treasure Gallery, a photo gallery from the voyage in the style of Instagram. You start with the photos alone, because they weigh the most in a gallery. Claude Code will show them with a component that takes care of size, format and loading order, and you will check in Cursor that it did it right.
What you will learn
- ask Claude Code for a page with photos from the project folder and from a foreign server;
- read the
width,height,fill,sizesandloadingprops of theImagecomponent; - check in
next.config.tsthat the list of allowed photo servers is narrow; - catch three typical agent mistakes: a plain
<img>,fillwithoutrelative, and analtthat says nothing.
A new port: the treasure-gallery project
Kraken's Call stays in its own port. It is a game with a messenger, while Instagram is a separate app with different data, so it gets its own project. You create it just like in lesson 1_2: open the projekty folder in Cursor, run claude and ask for a project with the same request as in lesson 1_2, changing only the name to treasure-gallery. Before you click Yes, compare the command with this one:
npx create-next-app@latest treasure-gallery --ts --eslint --tailwind --app --no-src-dir --no-cache-components --agents-md --no-agent-feedback --use-npmYou know the flags from lesson 1_2: TypeScript, ESLint, Tailwind CSS and App Router, without a src/ folder and without Cache Components. Then the loop from location 2: move the session into the treasure-gallery folder, ask for npm run build as proof, make a short CLAUDE.md with an @AGENTS.md import as in lesson 1_7 and save a commit. From now on every request in this location is about this project.
The problem: a phone photo weighs megabytes
Create a public/images/ folder in the project and drop three of your own photos into it, for example from your phone, named skarb-1.jpg, skarb-2.jpg and skarb-3.jpg. A fourth one, kapitan.jpg, will serve as the avatar. A phone photo is usually several thousand pixels wide and weighs megabytes, while a thumbnail in the gallery takes about 300 pixels on screen. A plain <img> tag still sends the browser the whole file. The page loads slowly, eats mobile data, and when photos arrive one by one, the text below them jumps down.
Image in one paragraph
Next.js has a component for this, Image from the next/image package, which extends a plain <img>. It prepares a copy of the photo in the size needed on a given screen, in the lighter WebP format. Photos lower on the page it loads lazily (lazy loading), that is, only when they get close to the visible part of the screen. It also reserves space for the image before the image arrives, so nothing jumps; that jumping has a name: Cumulative Layout Shift, CLS for short. In return Image wants to know what is in the photo (alt) and how big the image should be (width and height, or fill). Photos from foreign servers it lets through only from the list in next.config.ts.
Request for Claude Code
The gallery has two sources of photos: your public/images/ folder and three photos from the free Unsplash service. The request has a goal, files, constraints and a check, like in lesson 0_5:
Request for Claude Code:
Build a /gallery page in Treasure Gallery, a profile like on Instagram.
Keep the photo data in lib/photos.ts: id, src, alt, author and caption.
Three photos are in public/images/ (skarb-1.jpg, skarb-2.jpg,
skarb-3.jpg): look at them and write an alt that says what is in them.
Three more are from Unsplash:
https://images.unsplash.com/photo-1507525428034-b723cf961d3e
https://images.unsplash.com/photo-1505118380757-91f5f5632de0
https://images.unsplash.com/photo-1534447677768-be436bb09401
At the top a round avatar from public/images/kapitan.jpg (96 px) and a
title, below it square thumbnails in three columns. Use Image from
next/image everywhere, never <img>. In @next.config.ts allow only the
server images.unsplash.com and change nothing else in that file.
At the end run npm run build and npm run lint and show the results.The request "look at them" is not decoration: Claude Code reads PNG, JPEG, GIF and WebP files as images, so it will see for itself what is in your photos. The ban on other changes in next.config.ts protects the rest of the file, including the rule the wizard put there for Tailwind.
What Claude wrote: the photo data
Open lib/photos.ts in Cursor. At the top stands the photo type, below it an array of six entries. Here are two of them, a remote one and a local one:
export interface Photo {
id: string;
src: string;
alt: string;
author: string;
caption: string;
}
export const photos: Photo[] = [
{
id: "zachod-na-plazy",
src: "https://images.unsplash.com/photo-1507525428034-b723cf961d3e",
alt: "Waves on a sandy beach at sunset",
author: "Morgan",
caption: "We buried the chest here",
},
{
id: "skarb-1",
src: "/images/skarb-1.jpg",
alt: "Palm trees and a straw umbrella on a white beach",
author: "Captain Redbeard",
caption: "The island from the map",
},
];The src of a photo from the public/ folder starts with a slash and does not contain the word public: the file public/images/skarb-1.jpg is available at the address /images/skarb-1.jpg. A remote photo has a full address with https://. Your alt descriptions will be different, because Claude wrote them while looking at your photos.
The avatar: width and height
Open app/gallery/page.tsx. At the top is the import of the component: import Image from "next/image";. The page is a <main> with the max-w-4xl class, so it is at most 896 pixels wide. It starts with a profile header with the avatar:
<Image
src="/images/kapitan.jpg"
alt="Portrait of Captain Redbeard"
width={96}
height={96}
className="h-24 w-24 rounded-full object-cover"
/>width and height are the image dimensions in pixels. Next.js computes the proportions from them and reserves space before the file arrives, and it also uses them to choose the size of the copy. The size on screen is set by the classes: h-24 w-24 is 96 by 96 pixels, rounded-full makes a circle, and object-cover crops a photo that is not square. Both props are required, unless the image has fill or is imported from a file with an import statement.
Thumbnails: fill, sizes and loading
Under the header sits the grid. Each thumbnail is a square box with an image inside:
<div className="grid grid-cols-3 gap-1">
{photos.map((photo, index) => (
<div key={photo.id} className="relative aspect-square">
<Image
src={photo.src}
alt={photo.alt}
fill
sizes="(max-width: 896px) 33vw, 300px"
loading={index < 3 ? "eager" : "lazy"}
className="object-cover"
/>
</div>
))}
</div>We do not know the dimensions of phone and Unsplash photos, so Claude used fill: the image stretches over the whole parent box. The parent must have a relative, absolute or fixed position, here the relative class, and a height, which aspect-square gives, a square with a 1:1 ratio. object-cover fills the square and crops what sticks out, while object-contain would show the whole photo with empty bands.
sizes tells the browser how wide the image will be: in a window up to 896 pixels one third of the screen width (33vw), in a wider one 300 pixels. Without sizes the browser assumes that an image with fill takes the whole screen and downloads a file that is too big. loading decides when to load. By default an image loads lazily, and the first row, visible right after entering the page, Claude set to "eager", that is, right away.
The older priority prop is deprecated since Next.js 16, and the documentation in most cases recommends loading="eager" or fetchPriority="high" instead (as of November 2026). The starter page from the wizard still has priority on the Next.js logo, so do not take it as a model.
next.config.ts: the list of allowed servers
Open next.config.ts. The turbopack block with the Tailwind rule was left by the wizard, and Claude added only images below it:
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
/* config options here */
turbopack: {
rules: {
"*.css": {
loaders: ["@tailwindcss/turbopack"],
as: "*.css",
},
},
},
images: {
remotePatterns: [
{
protocol: "https",
hostname: "images.unsplash.com",
port: "",
pathname: "/**",
search: "",
},
],
},
};
export default nextConfig;remotePatterns is a list of address patterns from which Next.js may download and process images. This entry lets through only https, only the server images.unsplash.com, no other ports (port: "") and no parameters after the question mark (search: ""). /** in pathname means any path on that server. The documentation also shows a shorter form with a single address: remotePatterns: [new URL("https://images.unsplash.com/**")]. The npm run dev server notices a change in this file by itself and prints "Found a change in next.config.ts. Restarting the server", so you do not have to restart it. A photo from a server outside the list stops the page with this error:
Error: Invalid src prop (https://example.com/a.jpg) on `next/image`, hostname "example.com" is not configured under images in your `next.config.js`The message talks about next.config.js, but in a TypeScript project it means the same file in its next.config.ts version. The fix is a new entry on the list, always with a specific server.
Captain's review
Run npm run dev in a second terminal, open localhost:3000/gallery and check:
- No
<img>. Search the project for the text<img: there should be no hits inapp/. A plain tag does not break the build, and the linter only warns:
warning Using `<img>` could result in slower LCP and higher bandwidth. Consider using `<Image />` from `next/image` ... @next/next/no-img-elementA warning does not turn the result of npm run lint into an error, so read the command output and not only whether it finished.
fillwithoutrelative. A typical agent mistake: Claude addsfill, but the box above the image has no position. The photo then spills over the whole page, and the browser console shows:
Image with src "/images/skarb-1.jpg" has "fill" and parent element with invalid "position". Provided "static" should be one of absolute,fixed,relative.The fix is the relative class on the parent, not removing fill.
A narrow server list.
next.config.tshas nohostname: "**"and no entry withoutprotocol. The documentation warns that omitted fields act like a wildcard and let through addresses you did not plan for. Theturbopackblock stands untouched.altdescribes the photo. "Image", "photo 1" or a file name tell nothing to a person whose screen reader reads the page aloud. A goodaltreplaces the photo with words. For a purely decorative image the documentation says to write an emptyalt="".
Finally, proof that the optimization works: right-click a thumbnail and open the image in a new tab. The address starts with /_next/image?url= and has a w parameter, the width of the copy. In our test a 1.5 MB photo arrived as a copy 384 pixels wide, as a WebP file of about 21 KB.
Next step
When the review passes, ask for a commit, for example "Gallery: photos through next/image and a server list". Before the next lesson do one more thing, away from the computer: draw on a sheet of paper how the gallery should look after a click on a photo. A grid of thumbnails, and above it a window with a big photo, the author, the caption and a cross for closing. Take a photo of the sheet with your phone, because in lesson 3_2 Claude Code will build the window from exactly this sketch.
In the editor below you have square tiles with real photos. The editor has no Next.js server, so it uses a plain <img> with the classes that Image with fill gets in the project. Switch object-cover to object-contain and see where the cropping goes away, then solve the tasks.
Remember: you show the treasure at a size that fits in the spyglass, not the whole chest, and you let in only from the ports you wrote on the list yourself.
Code for this lesson: App.jsx
// Gallery tiles: object-cover versus object-contain
// In the Next.js project this is <Image fill className="object-cover" />.
// The editor has no Next.js server, so a plain <img> gets the classes
// that Image with fill sets by itself: absolute, full width and height.
import { useState } from 'react';
const photos = [
{
id: 'zachod-na-plazy',
src: 'https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=600',
alt: 'Waves on a sandy beach at sunset',
},
{
id: 'fale-z-gory',
src: 'https://images.unsplash.com/photo-1505118380757-91f5f5632de0?w=600',
alt: 'Turquoise waves at a white beach seen from above',
},
{
id: 'zaglowka-noca',
src: 'https://images.unsplash.com/photo-1534447677768-be436bb09401?w=600',
alt: 'A small sailboat on a calm sea under a starry sky',
},
];
const fits = ['object-cover', 'object-contain'];
export default function App() {
const [fit, setFit] = useState('object-cover');
return (
<div className="min-h-screen bg-slate-100 p-6 text-slate-900">
<h1 className="mb-1 text-2xl font-bold">Treasure Gallery</h1>
<p className="mb-4 text-sm text-slate-600">
The tile has relative and aspect-square, the photo fills it completely.
</p>
<div className="mb-4 flex gap-2">
{fits.map((option) => (
<button
key={option}
type="button"
onClick={() => setFit(option)}
aria-pressed={fit === option}
className={fit === option
? 'rounded bg-slate-900 px-3 py-1 text-sm text-white'
: 'rounded bg-white px-3 py-1 text-sm'}
>
{option}
</button>
))}
</div>
<div className="grid grid-cols-3 gap-1">
{photos.map((photo) => (
<div key={photo.id} className="relative aspect-square bg-slate-800">
<img
src={photo.src}
alt={photo.alt}
className={`absolute inset-0 h-full w-full ${fit}`}
/>
</div>
))}
</div>
<p className="mt-4 text-sm text-slate-600">
{fit === 'object-cover'
? 'object-cover: the square is full, the photo edges are cropped.'
: 'object-contain: the whole photo is visible, empty bands at the edges.'}
</p>
</div>
);
}Spotted a mistake in this lesson?
Check yourself
Answer the questions from this lesson. Pick an answer to see right away whether it is correct.
1. What does the Image component from next/image give you compared with a plain <img> tag?
2. In which format does Next.js by default send the optimized copy of a photo to a browser that supports that format?
These are 2 of 7 questions for this lesson. Solve the rest in the game.
Hands-on tasks in the game
- Click in order
Click the tokens in order to import the Image component from Next.js:
- Horizontal ordering
Arrange the pieces of the shorter form of the allowed photo servers list from next.config.ts (one line, from the left):
- Code editor
Image component
- Click in order
Click the pieces in order so that the first three thumbnails load right away and the rest lazily:
- Vertical ordering
Arrange the lines of next.config.ts with the allowed photo servers list (top to bottom):
- Code editor
Responsive image
- Horizontal ordering
The file is at public/images/skarby/skarb-1.jpg. Arrange the pieces of the src value you will put in Image:
Tasks after this lesson
- QuestionQuiz: Image Instead of img
- QuestionQuiz: Format of an Optimized Photo
- QuestionQuiz: Required Image Props
- Click in orderClick in order: Import the Image component
- Put in orderSorting: Short Form of remotePatterns
- Coding taskPractice: Basic Image
- QuestionQuiz: The fill Prop
- QuestionQuiz: object-cover and object-contain
- Click in orderClicking: When to Load Thumbnails
- Put in orderSorting: The next.config.ts File
- Coding taskPractice: Image with fill
- QuestionQuiz: Photos Visible Right Away
- QuestionQuiz: Photos from Foreign Servers
- Put in orderSorting: Path of a Photo from public