@kentcdodds/photo-portfolio
A fast, photo-first portfolio site you update by chatting with your agent: galleries, about, contact, and one-step rollback.
Files
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 withupdate-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 thepreviewUrlfrom the result. - Confirm before removing.
remove-galleryanddiscard-changesneedconfirm: 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
| Export | Example |
|---|---|
default (site-status) | await siteStatus() |
get-config | await getConfig({}) → { config, defaults, pendingConfigFields, liveUrl, previewUrl } |
update-config | await updateConfig({ tagline: 'Family & newborn photography', dryRun: true }) |
add-gallery | await addGallery({ title: 'Smith Family', photos: [{ url, alt }] }) |
add-photos | await addPhotos({ gallery: 'smith-family', photos: [{ base64, alt }] }) |
update-gallery | await updateGallery({ gallery: 'smith-family', coverPhotoId: 'ph_…' }) |
remove-photo | await removePhoto({ gallery: 'smith-family', photoId: 'ph_…' }) |
remove-gallery | await removeGallery({ gallery: 'golden-hour', confirm: true }) |
reorder-galleries | await reorderGalleries({ order: ['weddings', 'portraits'] }) |
list-galleries | await listGalleries({ from: 'live' }) |
get-preview-url | await getPreviewUrl({}) / await getPreviewUrl({ rotate: true }) |
publish-changes | await publishChanges({ note: 'Smith family gallery' }) |
discard-changes | await discardChanges({ confirm: true }) |
list-versions | await listVersions() |
rollback | await rollback({ version: 3 }) |
list-inquiries | await 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-photosin 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 key | Contents |
|---|---|
site/draft | Config + gallery manifest being edited |
site/live | What visitors see (absent on a fresh fork: bundled defaults are live) |
site/versions, site/version/<n> | Version index and snapshots |
site/preview-token | Current preview token |
site/hosted-url | Kody-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-budget | Contact 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
liveUrlin 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.
contactEmailis what visitors see. siteUrlonly 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.