Skip to content
← Public packages

@kentcdodds/photo-portfolio

A fast, photo-first portfolio site you update by chatting with your agent: galleries, about, contact, and one-step rollback.

FollowFork

Files

AGENTS.md

216 lines · 10.5 KB · Markdown

Photo Portfolio: agent guide

A photographer's portfolio site (package app) plus exports to manage it. The owner is usually not technical: do the work, show her the preview link, and confirm before anything destructive or public.

Imports below use @kentcdodds. In a fork, use the fork's own scope (for example kody:@janedoe/photo-portfolio/add-gallery).

Ground rules

  • Her details live in package storage, never in agent memory. Read them with get-config, change them with update-config. Do not save her name, email, phone, bio, or links to memory; read them fresh each time.
  • Everything edits the draft. Nothing is visible on the live site until publish-changes. After edits, send her the previewUrl from the result.
  • Confirm before removing. remove-gallery and discard-changes need confirm: true; call without it first and tell her what would change.
  • Publish only when she says so (or explicitly asked for it in one go). publish-changes({ dryRun: true }) shows what will change.
  • Every mutating input is strict: unknown keys throw with the offending path.

Start here

import siteStatus from 'kody:@kentcdodds/photo-portfolio'

const status = await siteStatus()
// {
//   siteName: 'Your Name Photography',
//   liveUrl: 'https://jane.kody.run/packages/photo-portfolio',
//   previewUrl: 'https://jane.kody.run/packages/photo-portfolio/preview?token=…',
//   canonicalUrl: null,
//   usingSampleContent: true,   // still showing the bundled sample galleries
//   galleries: 3, photos: 12, liveVersion: null,
//   pending: { hasChanges: false, configFields: [], galleriesAdded: [], … },
//   inquiries: { total: 0, latestAt: null },
// }

usingSampleContent: true on a new fork means: offer to set her details and replace the samples.

liveUrl/previewUrl are null (with a setup hint) until the app has been opened once: exports can't see the hosted URL, so the app records it in storage on its first request. Ask her to open the site from Kody once.

Exports

ExportExample
default (site-status)await siteStatus()
get-configawait getConfig({}) → { config, defaults, pendingConfigFields, liveUrl, previewUrl }
update-configawait updateConfig({ tagline: 'Family & newborn photography', dryRun: true })
add-galleryawait addGallery({ title: 'Smith Family', photos: [{ url, alt }] })
add-photosawait addPhotos({ gallery: 'smith-family', photos: [{ base64, alt }] })
update-galleryawait updateGallery({ gallery: 'smith-family', coverPhotoId: 'ph_…' })
remove-photoawait removePhoto({ gallery: 'smith-family', photoId: 'ph_…' })
remove-galleryawait removeGallery({ gallery: 'golden-hour', confirm: true })
reorder-galleriesawait reorderGalleries({ order: ['weddings', 'portraits'] })
list-galleriesawait listGalleries({ from: 'live' })
get-preview-urlawait getPreviewUrl({}) / await getPreviewUrl({ rotate: true })
publish-changesawait publishChanges({ note: 'Smith family gallery' })
discard-changesawait discardChanges({ confirm: true })
list-versionsawait listVersions()
rollbackawait rollback({ version: 3 })
list-inquiriesawait listInquiries({ since: '2026-10-01', limit: 10 })

Galleries are referenced by slug or id; photos by id (from list-galleries).

Config fields (update-config)
import updateConfig from 'kody:@kentcdodds/photo-portfolio/update-config'

await updateConfig({
	siteName: 'Jane Doe Photography',        // header and page titles
	tagline: 'Family & newborn photography', // home page headline
	photographerName: 'Jane Doe',
	bio: "Hi, I'm **Jane**.\n\nI photograph families in Austin.\n\n[Book a session](contact)",
	headshot: { url: 'https://example.com/jane.jpg', alt: 'Jane smiling outdoors' }, // or { base64 }, or null to remove
	contactEmail: 'jane@example.com',        // mailto link (inquiry emails go to her verified Kody address)
	phone: '(512) 555-0100',                 // null removes
	location: 'Austin, Texas',
	social: { instagram: 'https://instagram.com/janedoe', website: null },
	bookingUrl: 'https://cal.com/janedoe/session', // shows a "Book a session" button
	bookingLabel: 'Book a session',
	accentColor: '#3a6ea5',                  // links and buttons
	theme: 'auto',                           // 'auto' follows the visitor's device; or 'light' / 'dark'
	seoDescription: 'Austin family and newborn photographer.',
	siteUrl: 'https://janedoephoto.com',     // canonical origin, once a custom domain points here; null for the Kody URL
	notifyOnInquiry: true,                   // email her each contact-form message (30/day max)
	embedCopyright: true,                    // writes "© <year> <name>" into JPEG EXIF on new uploads
	showCameraDetails: false,                // camera · lens · exposure under photos
	dryRun: true,                            // returns { changes } without saving
})

Defaults for a fresh fork are in get-config → defaults. Bio markdown: paragraphs, #–### headings, -/1. lists, **bold**, *italic*, [links](https://…). Relative links like (contact) stay inside the site.

Photo batches

Each photo is decoded, rotated upright, resized to 480/960/1600/2400px (never upscaled), encoded as WebP and JPEG, stripped of GPS and other EXIF, and given a blur placeholder. That is CPU-heavy, so:

  • At most 6 photos per call (4 is a good batch). For a shoot of 30, create the gallery with the first 4, then add-photos in batches of 4.
  • Sources: { url } (direct link to the image file, not a share page) or { base64 } (data-URI prefix is fine). JPEG, PNG, or WebP; up to 30 MB and 12 megapixels. HEIC/AVIF fail with a message asking for JPEG.
  • Alt text matters (accessibility and search). Write a short description for each photo; it falls back to the caption, then "Photo from <gallery>".
  • A batch is all-or-nothing: if photo 3 of 4 fails, nothing is added and the error says Photo 3 of 4: ….
import addGallery from 'kody:@kentcdodds/photo-portfolio/add-gallery'
import addPhotos from 'kody:@kentcdodds/photo-portfolio/add-photos'

const { gallery, previewUrl } = await addGallery({
	title: 'Smith Family, Fall 2026',
	description: 'An evening at Zilker Park.',
	featured: true,      // shown on the home page (default true)
	position: 'start',   // newest first (default)
	cover: 0,            // index into photos
	photos: [
		{ url: 'https://example.com/smith-01.jpg', alt: 'Family of four laughing on a park bench', caption: 'Golden hour' },
		{ url: 'https://example.com/smith-02.jpg', alt: 'Two kids running through fallen leaves' },
	],
})
await addPhotos({
	gallery: gallery.slug,
	photos: [{ url: 'https://example.com/smith-03.jpg', alt: 'Grandmother holding the baby' }],
})

add-gallery({ …, draft: false }) adds and publishes in one call. It publishes every pending change, so only use it when she asked for that.

Preview → publish → rollback

import getPreviewUrl from 'kody:@kentcdodds/photo-portfolio/get-preview-url'
import publishChanges from 'kody:@kentcdodds/photo-portfolio/publish-changes'
import listVersions from 'kody:@kentcdodds/photo-portfolio/list-versions'
import rollback from 'kody:@kentcdodds/photo-portfolio/rollback'

const { previewUrl, pending } = await getPreviewUrl({})
// Opening previewUrl sets a 24h cookie: that browser sees the draft with a
// "Preview" bar and an "Exit preview" link. Anyone with the link can see the
// draft; rotate: true issues a new link and kills the old one.

await publishChanges({ dryRun: true })            // { published: false, changes }
await publishChanges({ note: 'Smith family' })    // { published: true, version: 4 }

const { versions } = await listVersions()         // newest first; versions[0] is live
await rollback({ version: 3, dryRun: true })      // what would change, and whether unpublished draft edits would be lost
await rollback({ version: 3 })                    // { rolledBack: true, version: 5, restoredFrom: 3 }
  • Versions snapshot content and settings (not the package code). The last 25 are kept; photos only used by older versions are deleted with them.
  • A rollback replaces the draft too (unpublished edits are discarded) and is itself a new version, so it can be undone.
  • discard-changes({ confirm: true }) throws away the draft instead.

Where things live

Storage keyContents
site/draftConfig + gallery manifest being edited
site/liveWhat visitors see (absent on a fresh fork: bundled defaults are live)
site/versions, site/version/<n>Version index and snapshots
site/preview-tokenCurrent preview token
site/hosted-urlKody-hosted app URL, recorded by the app for export links
media/index, media/<photoId>, media/<photoId>/<file>/<chunk>Encoded photo files (base64, 512K chunks)
inquiries, inquiries/notification-budgetContact messages (newest 500) and the daily email budget

Sample galleries ship as files in public/samples/ and are referenced by source: 'bundled' photos in src/domain/defaults.ts.

Site routes

/, /galleries, /galleries/<slug>, /galleries/<slug>/<photoId> (share URL and no-JS view), /about, /contact, /sitemap.xml, /robots.txt, /preview?token=…&to=/path, /preview/exit, /media/<photoId>/<width>.webp|jpg (immutable, cached a year), /health.

Gotchas

  • Access today: Kody package apps are served to the signed-in owner; the public can't open the site until Kody supports public package apps and custom domains. Check liveUrl in a private window before promising anything.
  • Inquiry email uses Kody's built-in email to the owner's verified address, with Reply-To set to the visitor. contactEmail is what visitors see.
  • siteUrl only changes canonical/OG/sitemap links. Set it after the custom domain actually serves the site.
  • Slugs change URLs. Renaming a gallery's slug breaks links already shared.
  • The draft and live site share stored photo files, so photos removed from the draft keep working live until the next publish.

Development

npm install
npm test   # node --test (config, manifest, versions/rollback, image pipeline)

Images are processed in pure JavaScript (jpeg-js, @stacksjs/ts-webp, blurhash, and a small PNG decoder on DecompressionStream in src/images/png.ts) because package bundles can't ship WebAssembly today. Avoid npm deps that pull in Node-only builds (e.g. fflate): the publish bundler resolves the node export condition, and Workers can't load module.