art-astro

Source of art.jamestannahill.com. Astro 6, fully static, deployed on every push to main. The design system (colors, type, components, motion, accessibility rules) is recorded in DESIGN.md.

Stack

• Astro 6.2: static output, file-based routing, View Transitions
• TypeScript + Astro Content Collections with Zod schemas
• DynamoDB → JSON snapshots at build time (no DB calls at runtime)
• Pagefind for local-first search across every piece's rationale
• Mapbox GL for the world-map page
• @astrojs/rss for /rss.xml
• CI: GitHub Actions: pull data → type-check → build → S3 sync → CloudFront invalidate

How it deploys

Every push to main runs .github/workflows/deploy.yml (it also runs daily at 07:17 UTC, after the upstream pipeline, and on manual workflow_dispatch):

1. npm run pull-data: scan DynamoDB art-generator table, write src/data/generated/{weather,palettes}.json (gitignored)
2. astro check: TypeScript validation across .astro files
3. npm run build:no-pull: astro build produces dist/ (~3,000 pages), then pagefind --site dist --output-subdir _pagefind builds the local search index
4. scripts/backfill-thumbs.py (via uv run): generates any WebP variants the resize Lambda has not written yet. Never fails the deploy.
5. aws s3 sync ./dist/ to the site/ prefix of the S3 bucket, in two passes: HTML and data with a 5-minute cache, _astro/* and images as immutable (no --delete: preserves pipeline-written PNG/WebP/SVG assets)
6. aws cloudfront create-invalidation --paths "/*"

End-to-end: ~45 s on a clean runner.

Image pipeline

Pieces are generated by the upstream art-weather-render Lambda (in art-generator), which writes weather/{run_id}/{slug}/preview-2048.png to S3.

The art-image-resize Lambda (S3 PUT-triggered, also in art-generator) builds the web previews preview-{480,960,1200,1920}.webp from the upscaled 4K master (preview-4k.png), falling back to preview-2048.png only when no master exists. The 1200 variant is the og:image. The asset-mirror Lambda (art-site-rebuild, the retired-and-shrunk legacy renderer) copies everything from weather/ to site/weather/ once per daily pipeline run so CloudFront's origin path serves the assets.

src/components/Thumb.astro renders <picture> with WebP <source srcset> at three widths (480/960/1920) plus PNG fallback. Card grids load ~30 KB WebP at 480 w instead of ~1.5 MB PNG.

Piece pages credit the model from the piece's renderer field (the visible "Model" and "Format" rows plus the JSON-LD artMedium): flux-dev-lora:* is "FLUX.1-dev + custom LoRA", flux-1.1-pro is "Flux 1.1 Pro", and anything else is a Claude SVG (Claude Sonnet 4 via Amazon Bedrock).

Local dev

npm install
npm run pull-data    # AWS creds from ~/.aws/credentials
npm run dev          # http://localhost:4321
npm run build        # pull-data + astro build + Pagefind index
npm run build:no-pull  # same, reusing the existing src/data/generated/*.json
npm test             # tsx --test src/lib/seo.test.ts (14 tests)

npm run build pulls data from AWS, so it needs DynamoDB read access to the art-generator table. Use build:no-pull to rebuild offline from the last pull. The tests cover titles and descriptions in src/lib/seo.ts, including piece H1s and that no title contains an em-dash.

Environment variables

Var	Purpose
PUBLIC_MAPBOX_TOKEN	Public client token for the /map/ globe. Schema-validated via astro:env.

CI reads from repo secrets. Local dev: copy .env.example to .env.

Source layout

scripts/
  pull-data.ts          DynamoDB → src/data/generated/*.json
src/
  content.config.ts     Zod schemas for weather + palettes collections
  components/
    Thumb.astro         <picture> with WebP srcset
    Methodology.astro   Bloomberg block for LoRA-trained artists
    ConsentBanner.astro Analytics consent banner
  data/
    artists.ts          16-artist roster + 7 LoRA configs
    counts.ts           Single source of truth for every site-wide count
    faq.ts              About-page FAQ (drives JSON-LD + accordion)
  lib/
    seo.ts              Page titles, descriptions, piece H1s
    seo.test.ts         node:test suite for seo.ts (npm test)
  layouts/
    Base.astro          Shared header, footer, search modal, subscribe form
  pages/
    index.astro         Homepage: today's run, then the paid Generate panel
    about.astro         /about/
    archive/[...page].astro    Paginated /archive/ (12 pages of 8 runs each)
    artist/index.astro          /artist/ index (artist-card mosaic)
    artist/[key]/[...page].astro  Per-artist gallery (60/page) + methodology block
    weather/[run_id]/           Per-run page
    weather/[run_id]/[slug]/    Single-piece page + print drawer (~2,700 of these)
    palettes/                   /palettes/ + per-location detail
    comparison/index.astro      Style comparison (10 cells × 3+ artists)
    map/index.astro             Mapbox dark globe with clustering
    studies/index.astro         Studies (empty until DynamoDB has them)
    search.astro                /search/ standalone Pagefind page
    rss.xml.ts                  RSS feed
    feed.xml.ts                 Legacy /feed.xml, same handler as rss.xml
    llms.txt.ts                 /llms.txt
    api/{today,runs,artists,palettes}.json.ts    Static JSON endpoints
    404.astro

Design and accessibility

DESIGN.md is the design record: tokens, type, components and the rules below. Current behavior worth knowing before editing:

• Titles use | as the separator and never an em-dash. This is enforced by src/lib/seo.test.ts. Unnamed grid cells title by their coordinates, e.g. "Region 30°N, 150°E", instead of a bare "Region".
• Print drawer (piece page) is a modal dialog: inert when closed, moves focus in on open, keeps Tab inside while open and returns focus on close. Print sizes are buttons with aria-pressed; sold-out sizes are disabled.
• Search dialog (in Base.astro) is modal with a focus trap and returns focus on close.
• Homepage: the paid Generate panel sits below Today's run under its own heading.
• View transitions: a thumbnail gets its view-transition-name only when clicked, so grid pages do not snapshot every thumb on navigation.
• Form controls inherit the serif (Newsreader) font. There is a skip link, prefers-reduced-motion rules and visible focus rings.

Related repos / infrastructure

• art-generator: upstream Lambdas + DynamoDB pipeline. Daily Step Function runs: art-weather-ingest → art-weather-render × 10 → art-satellite-ingest → art-palette-extract → (art-image-resize triggers on each PNG) → art-site-rebuild (asset mirror) → this repo's Astro build (manual or push-triggered).

• CloudFront: one distribution with origin path /site/.

• S3: the shared art-generator S3 bucket behind CloudFront. Astro publishes to site/, pipeline writes pieces under weather/ + palettes/, mirror copies them.

• IAM: a dedicated CI deploy user with scoped s3:*Object on site/*, dynamodb:Scan on art-generator, and cloudfront:CreateInvalidation on the distro.

• Security headers: CloudFront response headers policy art-jamestannahill-security-csp, mirrored in infra/response-headers-policy.json. The CSP is the source of truth for which third-party hosts the site may load: Mapbox, Google Fonts (style-src + font-src), and Google Analytics (script-src for googletagmanager, connect-src + img-src for the collect endpoints). Adding a third-party script without adding it here means it silently never runs. To apply a change (POLICY_ID is that policy's ID, from aws cloudfront list-response-headers-policies --type custom):

  aws cloudfront update-response-headers-policy \
    --id "$POLICY_ID" \
    --if-match "$(aws cloudfront get-response-headers-policy-config \
      --id "$POLICY_ID" --query ETag --output text)" \
    --response-headers-policy-config file://infra/response-headers-policy.json
  

Analytics

GA4 property art.jamestannahill.com (measurement ID G-5KG25EY8YL), loaded from public/scripts/analytics.js and gated by public/scripts/consent.js. gtag loads only after the visitor accepts.

Page views: gtag('config', ...) sends the first one, and astro:after-swap sends one per ClientRouter navigation. after-swap does not fire on the initial load, so views are not double-counted. consent.js binds from astro:page-load only, for the same reason.

Country detection reads a jt_country cookie set by the art-viewer-country-cookie CloudFront Function (viewer-response, infra/viewer-country-cookie.js) from the CloudFront-Viewer-Country header. /cdn-cgi/trace remains as a fallback but 404s here: this is CloudFront, not Cloudflare.

CloudFront only populates CloudFront-Viewer-* headers when a policy asks for them, so the default behavior uses cache policy art-caching-optimized-viewer-country (mirrored in infra/cache-policy.json) rather than the managed CachingOptimized policy. It is CachingOptimized plus that one header, which means the header is part of the cache key and pages cache per country. Reverting to a policy without the header silently makes the banner show to everyone again, because the function has no country to copy.

Migration history

Originally a parallel staging build at /next/ while the Jinja2 renderer in art-generator/lambdas/site_rebuild/ owned the apex. Cut over on 2026-05-06. The legacy Lambda was shrunk to a ~50-line asset-mirror; templates were retired.