From d27b5be74f02a04900329143f3b381387a677976 Mon Sep 17 00:00:00 2001 From: maxitect Date: Thu, 12 Nov 2026 19:44:30 +0000 Subject: [PATCH 01/17] refactor(app): move site routes into frontend route group --- src/app/{ => (frontend)}/[...slug]/route.ts | 0 src/app/{ => (frontend)}/_components/HomeClient.tsx | 0 .../{ => (frontend)}/_components/SpinningLogo.tsx | 0 src/app/{ => (frontend)}/_components/StaticLogo.tsx | 0 .../about/_components/AboutClient.tsx | 0 src/app/{ => (frontend)}/about/page.tsx | 0 src/app/{ => (frontend)}/api/send-emails/route.ts | 0 src/app/{ => (frontend)}/apple-icon.png | Bin .../contact/_components/Checkbox.tsx | 0 .../contact/_components/ContactClient.tsx | 2 +- .../contact/_components/ContactForm.tsx | 2 +- .../contact/_components/TextInput.tsx | 0 src/app/{ => (frontend)}/contact/page.tsx | 0 src/app/{ => (frontend)}/globals.css | 0 src/app/{ => (frontend)}/icon.svg | 0 src/app/{ => (frontend)}/layout.tsx | 4 ++-- src/app/{ => (frontend)}/llms.txt/route.ts | 0 .../lyrics/_components/LyricsClient.tsx | 0 src/app/{ => (frontend)}/lyrics/page.tsx | 0 .../merch/_components/MerchClient.tsx | 0 src/app/{ => (frontend)}/merch/page.tsx | 0 .../{ => (frontend)}/music/_components/Bandcamp.tsx | 0 .../music/_components/MusicClient.tsx | 0 .../{ => (frontend)}/music/_components/Spotify.tsx | 0 .../{ => (frontend)}/music/_components/Youtube.tsx | 0 src/app/{ => (frontend)}/music/page.tsx | 0 src/app/{ => (frontend)}/opengraph-image.jpg | Bin src/app/{ => (frontend)}/page.tsx | 0 .../_components/PrivacyPolicyClient.tsx | 0 src/app/{ => (frontend)}/privacy-policy/page.tsx | 0 .../tour/_components/TourClient.tsx | 0 .../{ => (frontend)}/tour/_components/TourDate.tsx | 4 ++-- .../tour/_components/TourDatesContainer.tsx | 0 src/app/{ => (frontend)}/tour/page.tsx | 0 src/app/{ => (frontend)}/twitter-image.jpg | Bin 35 files changed, 6 insertions(+), 6 deletions(-) rename src/app/{ => (frontend)}/[...slug]/route.ts (100%) rename src/app/{ => (frontend)}/_components/HomeClient.tsx (100%) rename src/app/{ => (frontend)}/_components/SpinningLogo.tsx (100%) rename src/app/{ => (frontend)}/_components/StaticLogo.tsx (100%) rename src/app/{ => (frontend)}/about/_components/AboutClient.tsx (100%) rename src/app/{ => (frontend)}/about/page.tsx (100%) rename src/app/{ => (frontend)}/api/send-emails/route.ts (100%) rename src/app/{ => (frontend)}/apple-icon.png (100%) rename src/app/{ => (frontend)}/contact/_components/Checkbox.tsx (100%) rename src/app/{ => (frontend)}/contact/_components/ContactClient.tsx (94%) rename src/app/{ => (frontend)}/contact/_components/ContactForm.tsx (99%) rename src/app/{ => (frontend)}/contact/_components/TextInput.tsx (100%) rename src/app/{ => (frontend)}/contact/page.tsx (100%) rename src/app/{ => (frontend)}/globals.css (100%) rename src/app/{ => (frontend)}/icon.svg (100%) rename src/app/{ => (frontend)}/layout.tsx (95%) rename src/app/{ => (frontend)}/llms.txt/route.ts (100%) rename src/app/{ => (frontend)}/lyrics/_components/LyricsClient.tsx (100%) rename src/app/{ => (frontend)}/lyrics/page.tsx (100%) rename src/app/{ => (frontend)}/merch/_components/MerchClient.tsx (100%) rename src/app/{ => (frontend)}/merch/page.tsx (100%) rename src/app/{ => (frontend)}/music/_components/Bandcamp.tsx (100%) rename src/app/{ => (frontend)}/music/_components/MusicClient.tsx (100%) rename src/app/{ => (frontend)}/music/_components/Spotify.tsx (100%) rename src/app/{ => (frontend)}/music/_components/Youtube.tsx (100%) rename src/app/{ => (frontend)}/music/page.tsx (100%) rename src/app/{ => (frontend)}/opengraph-image.jpg (100%) rename src/app/{ => (frontend)}/page.tsx (100%) rename src/app/{ => (frontend)}/privacy-policy/_components/PrivacyPolicyClient.tsx (100%) rename src/app/{ => (frontend)}/privacy-policy/page.tsx (100%) rename src/app/{ => (frontend)}/tour/_components/TourClient.tsx (100%) rename src/app/{ => (frontend)}/tour/_components/TourDate.tsx (95%) rename src/app/{ => (frontend)}/tour/_components/TourDatesContainer.tsx (100%) rename src/app/{ => (frontend)}/tour/page.tsx (100%) rename src/app/{ => (frontend)}/twitter-image.jpg (100%) diff --git a/src/app/[...slug]/route.ts b/src/app/(frontend)/[...slug]/route.ts similarity index 100% rename from src/app/[...slug]/route.ts rename to src/app/(frontend)/[...slug]/route.ts diff --git a/src/app/_components/HomeClient.tsx b/src/app/(frontend)/_components/HomeClient.tsx similarity index 100% rename from src/app/_components/HomeClient.tsx rename to src/app/(frontend)/_components/HomeClient.tsx diff --git a/src/app/_components/SpinningLogo.tsx b/src/app/(frontend)/_components/SpinningLogo.tsx similarity index 100% rename from src/app/_components/SpinningLogo.tsx rename to src/app/(frontend)/_components/SpinningLogo.tsx diff --git a/src/app/_components/StaticLogo.tsx b/src/app/(frontend)/_components/StaticLogo.tsx similarity index 100% rename from src/app/_components/StaticLogo.tsx rename to src/app/(frontend)/_components/StaticLogo.tsx diff --git a/src/app/about/_components/AboutClient.tsx b/src/app/(frontend)/about/_components/AboutClient.tsx similarity index 100% rename from src/app/about/_components/AboutClient.tsx rename to src/app/(frontend)/about/_components/AboutClient.tsx diff --git a/src/app/about/page.tsx b/src/app/(frontend)/about/page.tsx similarity index 100% rename from src/app/about/page.tsx rename to src/app/(frontend)/about/page.tsx diff --git a/src/app/api/send-emails/route.ts b/src/app/(frontend)/api/send-emails/route.ts similarity index 100% rename from src/app/api/send-emails/route.ts rename to src/app/(frontend)/api/send-emails/route.ts diff --git a/src/app/apple-icon.png b/src/app/(frontend)/apple-icon.png similarity index 100% rename from src/app/apple-icon.png rename to src/app/(frontend)/apple-icon.png diff --git a/src/app/contact/_components/Checkbox.tsx b/src/app/(frontend)/contact/_components/Checkbox.tsx similarity index 100% rename from src/app/contact/_components/Checkbox.tsx rename to src/app/(frontend)/contact/_components/Checkbox.tsx diff --git a/src/app/contact/_components/ContactClient.tsx b/src/app/(frontend)/contact/_components/ContactClient.tsx similarity index 94% rename from src/app/contact/_components/ContactClient.tsx rename to src/app/(frontend)/contact/_components/ContactClient.tsx index 53d610b..85573d2 100644 --- a/src/app/contact/_components/ContactClient.tsx +++ b/src/app/(frontend)/contact/_components/ContactClient.tsx @@ -1,6 +1,6 @@ "use client"; -import ContactForm from "@/app/contact/_components/ContactForm"; +import ContactForm from "./ContactForm"; import { useLanguage } from "@/context/LanguageContext"; import { Page } from "@/utils/types"; import { useEffect } from "react"; diff --git a/src/app/contact/_components/ContactForm.tsx b/src/app/(frontend)/contact/_components/ContactForm.tsx similarity index 99% rename from src/app/contact/_components/ContactForm.tsx rename to src/app/(frontend)/contact/_components/ContactForm.tsx index 70de0ca..bbb757a 100644 --- a/src/app/contact/_components/ContactForm.tsx +++ b/src/app/(frontend)/contact/_components/ContactForm.tsx @@ -9,7 +9,7 @@ import Checkbox from "./Checkbox"; import { useLanguage } from "@/context/LanguageContext"; import contact_form from "@/data/contact_form.json"; -import Button from "../../../components/ui/Button"; +import Button from "@/components/ui/Button"; export default function ContactForm({ legend }: { legend: string }) { const contactForm = contact_form.reduce<{ [key: string]: string }>( diff --git a/src/app/contact/_components/TextInput.tsx b/src/app/(frontend)/contact/_components/TextInput.tsx similarity index 100% rename from src/app/contact/_components/TextInput.tsx rename to src/app/(frontend)/contact/_components/TextInput.tsx diff --git a/src/app/contact/page.tsx b/src/app/(frontend)/contact/page.tsx similarity index 100% rename from src/app/contact/page.tsx rename to src/app/(frontend)/contact/page.tsx diff --git a/src/app/globals.css b/src/app/(frontend)/globals.css similarity index 100% rename from src/app/globals.css rename to src/app/(frontend)/globals.css diff --git a/src/app/icon.svg b/src/app/(frontend)/icon.svg similarity index 100% rename from src/app/icon.svg rename to src/app/(frontend)/icon.svg diff --git a/src/app/layout.tsx b/src/app/(frontend)/layout.tsx similarity index 95% rename from src/app/layout.tsx rename to src/app/(frontend)/layout.tsx index 43c6cdf..f2277fb 100644 --- a/src/app/layout.tsx +++ b/src/app/(frontend)/layout.tsx @@ -23,13 +23,13 @@ const jost = Jost({ }); const blanchCaps = localFont({ - src: "../fonts/Blanch-Caps.woff2", + src: "../../fonts/Blanch-Caps.woff2", variable: "--next-font-blanch", display: "swap", }); const goudyStd = localFont({ - src: "../fonts/GoudyStd-Heavyface.woff2", + src: "../../fonts/GoudyStd-Heavyface.woff2", variable: "--next-font-goudy", display: "swap", }); diff --git a/src/app/llms.txt/route.ts b/src/app/(frontend)/llms.txt/route.ts similarity index 100% rename from src/app/llms.txt/route.ts rename to src/app/(frontend)/llms.txt/route.ts diff --git a/src/app/lyrics/_components/LyricsClient.tsx b/src/app/(frontend)/lyrics/_components/LyricsClient.tsx similarity index 100% rename from src/app/lyrics/_components/LyricsClient.tsx rename to src/app/(frontend)/lyrics/_components/LyricsClient.tsx diff --git a/src/app/lyrics/page.tsx b/src/app/(frontend)/lyrics/page.tsx similarity index 100% rename from src/app/lyrics/page.tsx rename to src/app/(frontend)/lyrics/page.tsx diff --git a/src/app/merch/_components/MerchClient.tsx b/src/app/(frontend)/merch/_components/MerchClient.tsx similarity index 100% rename from src/app/merch/_components/MerchClient.tsx rename to src/app/(frontend)/merch/_components/MerchClient.tsx diff --git a/src/app/merch/page.tsx b/src/app/(frontend)/merch/page.tsx similarity index 100% rename from src/app/merch/page.tsx rename to src/app/(frontend)/merch/page.tsx diff --git a/src/app/music/_components/Bandcamp.tsx b/src/app/(frontend)/music/_components/Bandcamp.tsx similarity index 100% rename from src/app/music/_components/Bandcamp.tsx rename to src/app/(frontend)/music/_components/Bandcamp.tsx diff --git a/src/app/music/_components/MusicClient.tsx b/src/app/(frontend)/music/_components/MusicClient.tsx similarity index 100% rename from src/app/music/_components/MusicClient.tsx rename to src/app/(frontend)/music/_components/MusicClient.tsx diff --git a/src/app/music/_components/Spotify.tsx b/src/app/(frontend)/music/_components/Spotify.tsx similarity index 100% rename from src/app/music/_components/Spotify.tsx rename to src/app/(frontend)/music/_components/Spotify.tsx diff --git a/src/app/music/_components/Youtube.tsx b/src/app/(frontend)/music/_components/Youtube.tsx similarity index 100% rename from src/app/music/_components/Youtube.tsx rename to src/app/(frontend)/music/_components/Youtube.tsx diff --git a/src/app/music/page.tsx b/src/app/(frontend)/music/page.tsx similarity index 100% rename from src/app/music/page.tsx rename to src/app/(frontend)/music/page.tsx diff --git a/src/app/opengraph-image.jpg b/src/app/(frontend)/opengraph-image.jpg similarity index 100% rename from src/app/opengraph-image.jpg rename to src/app/(frontend)/opengraph-image.jpg diff --git a/src/app/page.tsx b/src/app/(frontend)/page.tsx similarity index 100% rename from src/app/page.tsx rename to src/app/(frontend)/page.tsx diff --git a/src/app/privacy-policy/_components/PrivacyPolicyClient.tsx b/src/app/(frontend)/privacy-policy/_components/PrivacyPolicyClient.tsx similarity index 100% rename from src/app/privacy-policy/_components/PrivacyPolicyClient.tsx rename to src/app/(frontend)/privacy-policy/_components/PrivacyPolicyClient.tsx diff --git a/src/app/privacy-policy/page.tsx b/src/app/(frontend)/privacy-policy/page.tsx similarity index 100% rename from src/app/privacy-policy/page.tsx rename to src/app/(frontend)/privacy-policy/page.tsx diff --git a/src/app/tour/_components/TourClient.tsx b/src/app/(frontend)/tour/_components/TourClient.tsx similarity index 100% rename from src/app/tour/_components/TourClient.tsx rename to src/app/(frontend)/tour/_components/TourClient.tsx diff --git a/src/app/tour/_components/TourDate.tsx b/src/app/(frontend)/tour/_components/TourDate.tsx similarity index 95% rename from src/app/tour/_components/TourDate.tsx rename to src/app/(frontend)/tour/_components/TourDate.tsx index ff3452f..419d618 100644 --- a/src/app/tour/_components/TourDate.tsx +++ b/src/app/(frontend)/tour/_components/TourDate.tsx @@ -1,8 +1,8 @@ import Link from "next/link"; -import { TourDateType } from "../../../utils/types"; +import { TourDateType } from "@/utils/types"; import { useLanguage } from "@/context/LanguageContext"; -import Button from "../../../components/ui/Button"; +import Button from "@/components/ui/Button"; import clsx from "clsx"; interface TourDateProps { diff --git a/src/app/tour/_components/TourDatesContainer.tsx b/src/app/(frontend)/tour/_components/TourDatesContainer.tsx similarity index 100% rename from src/app/tour/_components/TourDatesContainer.tsx rename to src/app/(frontend)/tour/_components/TourDatesContainer.tsx diff --git a/src/app/tour/page.tsx b/src/app/(frontend)/tour/page.tsx similarity index 100% rename from src/app/tour/page.tsx rename to src/app/(frontend)/tour/page.tsx diff --git a/src/app/twitter-image.jpg b/src/app/(frontend)/twitter-image.jpg similarity index 100% rename from src/app/twitter-image.jpg rename to src/app/(frontend)/twitter-image.jpg From 5d95aaa23dfd9568cfba8cb8f3ce05e9e0d4d5c3 Mon Sep 17 00:00:00 2001 From: maxitect Date: Thu, 12 Nov 2026 19:45:02 +0000 Subject: [PATCH 02/17] chore(neon): ignore local project link file --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 2c94c88..1fd6a96 100644 --- a/.gitignore +++ b/.gitignore @@ -43,3 +43,4 @@ next-env.d.ts # netlify .netlify +.neon From bbbbb1e311d749d4f5b39379853c3c67085a8fac Mon Sep 17 00:00:00 2001 From: maxitect Date: Thu, 12 Nov 2026 20:13:46 +0000 Subject: [PATCH 03/17] docs(database): add rules for payload collections and migrations --- .claude/rules/database.md | 87 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 .claude/rules/database.md diff --git a/.claude/rules/database.md b/.claude/rules/database.md new file mode 100644 index 0000000..8039fd8 --- /dev/null +++ b/.claude/rules/database.md @@ -0,0 +1,87 @@ +--- +paths: + - "src/collections/**" + - "src/payload.config.ts" + - "src/migrations/**" +--- + +# Database Rules + +Payload generates the Postgres schema from the collection config in `src/collections/`. The schema is designed by choosing fields, not by writing tables. These rules are non-negotiable. A PR that breaks one is rejected. + +## Ownership + +- **Payload owns** the `payload_*` tables (`payload_migrations`, `payload_preferences`, `payload_locked_documents`, `payload_kv` and their `_rels`), `users_sessions`, and the `id`, `created_at` and `updated_at` columns on every table. Never write to them, alter them or query them from site code. They hold `jsonb` and generic `_rels` joins; that is Payload's business and exempt from the rules below. +- **We own** every collection: its fields, names, constraints and access. +- Read and write through Payload's local API (`getPayload`, `payload.find`). Reach for `payload.db.drizzle` only for a query the local API cannot express, and say why in the PR. + +## Normalisation + +- **3NF.** Every field depends on the document it sits on, the whole document and nothing but the document. +- **Don't store anything derivable.** Whether a tour date is past or upcoming comes from `eventDate` at render time. An embed URL comes from the stored ID. Never add a field the page can compute. +- **Atomic columns only.** These field types are banned in our collections because they store composite data in one `jsonb` column: + - `json` + - `richText` (Lexical state is a JSON tree). Use `textarea` for multi-line copy and lyrics. + - `blocks` + - `point`, and any delimited or encoded text (no "a,b,c" in a `text` field). +- **Repeating data** is an `array` field. Payload stores it as a child table `_` keyed by parent and order, with a real foreign key. +- **Controlled redundancy** is allowed only when the database keeps it consistent, through a constraint or trigger in a hand-written migration. Site code never syncs a redundant value. Every case goes in the register at the end of this file. + +## Relationships + +- **No polymorphic relationships.** `relationTo` is always one collection slug, never an array. +- **No `hasMany` on `relationship` or `upload` fields.** Payload stores those in a generic `_rels` table with one nullable column per target and a text `path`, so nothing guarantees a row points where the field says. For many-to-many, use an `array` field holding one single `relationship`, or a join collection with two single relationships. +- A single `relationship` or `upload` becomes a `_id` column with a foreign key. That is the only shape we use. +- Check the generated migration: a `_rels` table for one of our collections means a rule was broken. + +## Languages + +- The site is English and French. Translatable text uses Payload localisation: `localization: { locales: ['en', 'fr'], defaultLocale: 'en', fallback: true }` in the config and `localized: true` on the field. Payload moves those columns to `_locales`, one row per document per locale. +- Never pair fields by language (`titleEn` and `titleFr`, `lyrics` and `paroles`). +- Language-neutral data stays unlocalised: dates, URLs, venue and city names, embed IDs, images. +- Read with the visitor's locale and `fallbackLocale: 'en'`. + +## Enums, lookups and checks + +- A fixed option set that carries only a name is a `select` field. Payload creates a Postgres enum `enum__`; changing the options needs a migration. `hasMany` on a `select` is fine: it becomes a child table of enum values. +- A lookup is its own collection, and only when the options carry extra attributes or editors must add options without a deploy. State the reason in the PR. +- `required`, `unique` and `index` on a field become `NOT NULL`, a unique index and an index. Use them; they are the first line of integrity. +- Numeric ranges and cross-field rules that must hold for direct SQL too go in a `CHECK` constraint in a hand-written migration. Rules that only shape editor input go in the field's `validate`. + +## Naming + +- Collection slugs are plural kebab-case (`tour-dates`); Payload snake-cases them for tables. Field names are camelCase. +- Don't set `dbName` unless a generated name exceeds Postgres's 63 characters. +- IDs are Payload's default serial integers. Don't switch `idType` once data exists. + +## Access + +- Every collection declares `access` explicitly. Payload's access functions are the only row-level security here. +- `read: () => true` only for content the public site shows. `create`, `update` and `delete` stay at the default (signed-in users). +- The `users` collection is never publicly readable. + +## Migrations + +- `src/migrations/` is written by `pnpm exec payload migrate:create ` and applied by `pnpm exec payload migrate`. One concern per migration. +- Read the generated SQL before committing it. Reject `jsonb` columns and `_rels` tables on our collections. +- Hand-written SQL (triggers, functions, `CHECK` constraints, partial indexes) goes in its own blank migration: `pnpm exec payload migrate:create --force-accept-warning`. Never mix it into a generated one. Payload's generator does not know these objects exist, so a later rename can orphan them: list each one in the register below. +- Never edit a migration after it has merged. A migration must work with the previous deploy still running. +- `pnpm dev` pushes the schema straight to whatever `DATABASE_URL` points at. `.env.local` must point at the Neon `dev` branch, never `preview` or `main`. Those two change only through `payload migrate`. +- `src/payload-types.ts` and `src/app/(payload)/` are generated. Regenerate (`payload generate:types`, `payload generate:importmap`); never hand-edit. Derive every content type in site code from `payload-types.ts`. + +## Uploads + +- Files live in Neon Object Storage through `@payloadcms/storage-s3`; the `media` table holds the key and metadata, never the bytes. +- Storage branches with the database. A file uploaded on `preview` does not exist on `main`. + +## Proof + +There is no test framework. Every constraint, trigger and hand-written index is proven on the Neon `dev` branch with SQL (the `db` method in `docs/tickets/INSTRUCTIONS.md` §3): show that valid data passes and that the misuse it guards against fails. + +## Register of departures + +Every denormalisation, banned field type used anyway, and hand-written database object, with its reason and the migration that holds it. + +| Object | Kind | Reason | Migration | +| --- | --- | --- | --- | +| None yet | | | | From 5307b05557324b9e797503c5e9789524695928ad Mon Sep 17 00:00:00 2001 From: maxitect Date: Thu, 12 Nov 2026 20:13:52 +0000 Subject: [PATCH 04/17] docs(skills): add payload-collection skill --- .claude/skills/payload-collection/SKILL.md | 71 ++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 .claude/skills/payload-collection/SKILL.md diff --git a/.claude/skills/payload-collection/SKILL.md b/.claude/skills/payload-collection/SKILL.md new file mode 100644 index 0000000..6452c39 --- /dev/null +++ b/.claude/skills/payload-collection/SKILL.md @@ -0,0 +1,71 @@ +--- +name: payload-collection +description: Add or change a Payload collection end to end (config, generated types, migration, proof on a Neon branch) following .claude/rules/database.md. Use when adding a collection, adding, renaming or removing a field, or writing a hand-made constraint or trigger. +--- + +# Payload Collection + +Changes one collection in `src/collections/`, following `.claude/rules/database.md`. Copy the nearest existing collection (`TourDates.ts` for content, `Media.ts` for uploads) and adapt it. + +Every Neon command needs the Tandem profile: `export NEON_PROFILE=tandem`. The `--profile` flag alone is not enough for project-scoped commands. + +## 0. Read first + +- `.claude/rules/database.md`, all of it. +- The Payload docs for each field type you plan to use, through context7 (`/websites/payloadcms`). Field options change between minor versions. +- `.neon` must say `"branch": "dev"`. If not, run `neon checkout dev` before starting the dev server. + +## 1. Design + +For each piece of data, decide before writing config: + +1. Is it derivable? Then it is not a field. +2. Is it translatable text? Then `localized: true`. Dates, URLs, names of places and IDs are not. +3. Does it repeat? Then an `array` field, never delimited text. +4. Does it point at another document? Then one `relationship` or `upload` with a single `relationTo` and no `hasMany`. +5. Is it one of a fixed set? Then `select`. + +If the answer needs `json`, `richText`, `blocks`, a polymorphic `relationTo` or a `hasMany` relationship, stop and ask. A yes goes in the register in `database.md`. + +## 2. Config + +1. Write or edit `src/collections/.ts`: export a `CollectionConfig` with a plural kebab-case `slug`, `admin.useAsTitle`, explicit `access`, and the fields with `required`, `unique` and `index` set where they hold. +2. A new collection is added to `collections` in `src/payload.config.ts`. An upload collection that stores files is also added to the `s3Storage` plugin's `collections`. +3. Run `pnpm exec payload generate:types`. Run `pnpm exec payload generate:importmap` if the admin gained a custom component. + +## 3. Try it on `dev` + +1. `pnpm dev --port <4000 + issue number>`. Dev mode pushes the schema to the `dev` branch. +2. In `/admin`, create, edit and delete a document. Read the dev server output for errors. +3. Stop the server by port. + +## 4. Migration + +1. `pnpm exec payload migrate:create `. +2. Read the generated SQL in `src/migrations/`. It must contain no `jsonb` column and no `_rels` table for our collections, and each relationship must be a `_id` column with a foreign key. +3. A rename shows up as drop and add, which loses data. Write the `ALTER TABLE … RENAME` by hand in that migration instead and say so in the PR. + +## 5. Hand-written objects + +Only when a rule must hold for direct SQL too. + +1. `pnpm exec payload migrate:create --force-accept-warning` writes a blank migration. Put the SQL in `up` and its reverse in `down`, using `db.execute(sql\`…\`)`. +2. Functions set `search_path` explicitly and are not `SECURITY DEFINER` unless they must be. +3. Add the object to the register in `database.md`. + +## 6. Apply to `preview` and prove + +1. Pull the `preview` branch's variables to a file outside the working tree: `neon env pull --branch preview --file .git/ticket//artefacts/preview.env`. Never print it. +2. With `.env.local` and then that file loaded into the shell, run `pnpm exec payload migrate`. +3. Prove with SQL through `neon psql preview -- -Atc ""`: the table and columns exist, valid data passes, and each constraint rejects what it guards against. Keep the output for the PR. +4. After the PR's deploy preview is ready, create a document in the preview's admin and load the page that shows it. + +## 7. Production + +Never run a migration against `main`. List the step in the PR's notes for the user: `payload migrate` against the `main` branch, and any environment variable the change needs. + +## 8. Using the content + +- Server components read with `getPayload({ config })` and `payload.find`, passing the visitor's locale and `fallbackLocale: 'en'`. +- Types come from `src/payload-types.ts`. Never write a type by hand for collection data. +- With `cacheComponents` on, a read is either inside `"use cache"` with a `cacheTag`, or inside `` after `await connection()`. Invoke `vercel:next-cache-components` first. From 02fdd33ba24957e16bfbeb9d167a0abea64cdac3 Mon Sep 17 00:00:00 2001 From: maxitect Date: Thu, 12 Nov 2026 20:13:58 +0000 Subject: [PATCH 05/17] docs(tickets): point to neon project and payload-collection skill --- docs/tickets/INSTRUCTIONS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/tickets/INSTRUCTIONS.md b/docs/tickets/INSTRUCTIONS.md index eaac24a..c1f4aeb 100644 --- a/docs/tickets/INSTRUCTIONS.md +++ b/docs/tickets/INSTRUCTIONS.md @@ -109,6 +109,7 @@ Invoke the skill before writing code that needs it. | `netlify.toml`, redirects, headers, environment variables | `netlify-skills:netlify-config`, `netlify-skills:netlify-frameworks` | | Netlify functions, caching, image CDN | `netlify-skills:netlify-functions`, `netlify-skills:netlify-caching`, `netlify-skills:netlify-image-cdn` | | Neon Postgres and object storage | `neon:neon-postgres`, `neon:neon-object-storage` | +| A Payload collection, field or migration | `payload-collection` (rules in `.claude/rules/database.md`) | | Zod schemas | `zod4` | | A stacked branch that needs rebasing | `gh-stack` | | New or reshaped UI | `frontend-design:frontend-design` | @@ -128,7 +129,7 @@ The Netlify, Neon and GitHub tools are installed and signed in. Use them to find | Build | `@netlify/plugin-nextjs`; settings are in the Netlify UI until `netlify.toml` lands (#26) | | Free plan limits | 100 GB bandwidth, 300 build minutes and 125,000 function calls a month. Each push to a PR costs a build, so push as few times as you can | | Environment variables | `EMAIL_HOST`, `EMAIL_PORT`, `EMAIL_SECURE`, `EMAIL_USER`, `EMAIL_PASSWORD` (secret), `NEXT_PUBLIC_CSV_URL` | -| Database | None yet. Payload on Neon Postgres with Neon Object Storage is planned (#32, #33); Frankfurt region, free plan | +| Database | Neon project `cbc` (`damp-truth-56586096`), Frankfurt, free plan, in the Tandem Neon account: run Neon commands with `NEON_PROFILE=tandem`. Branches: `main` (production, empty until the migration), `preview` (shared by every deploy preview), `dev` (local). Bucket `media` on each branch. Spiked in #32; migration in #33 | Reads are always fine: deploy logs (`netlify api getDeploy`, `listSiteDeploys`), variable names, DNS lookups. Anything that changes a hosted service needs the user's approval first; agents ask the `/tickets` driver, and the driver asks the user. From 55ca6eb22307c5ea224a0ddc5286aecffba7aa78 Mon Sep 17 00:00:00 2001 From: maxitect Date: Thu, 12 Nov 2026 20:14:03 +0000 Subject: [PATCH 06/17] chore(git): ignore session handover log --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 1fd6a96..a0cb4ff 100644 --- a/.gitignore +++ b/.gitignore @@ -44,3 +44,6 @@ next-env.d.ts # netlify .netlify .neon + +# session handover log +PROMPT.md From bf08ee2955b01db35f361a10eda4e010b4c92889 Mon Sep 17 00:00:00 2001 From: maxitect Date: Thu, 12 Nov 2026 20:26:14 +0000 Subject: [PATCH 07/17] docs(database): correct payload storage claims and align rules with skill --- .claude/rules/database.md | 27 ++++++++++++---------- .claude/skills/payload-collection/SKILL.md | 21 ++++++++++++----- 2 files changed, 30 insertions(+), 18 deletions(-) diff --git a/.claude/rules/database.md b/.claude/rules/database.md index 8039fd8..34569c7 100644 --- a/.claude/rules/database.md +++ b/.claude/rules/database.md @@ -19,11 +19,13 @@ Payload generates the Postgres schema from the collection config in `src/collect - **3NF.** Every field depends on the document it sits on, the whole document and nothing but the document. - **Don't store anything derivable.** Whether a tour date is past or upcoming comes from `eventDate` at render time. An embed URL comes from the stored ID. Never add a field the page can compute. -- **Atomic columns only.** These field types are banned in our collections because they store composite data in one `jsonb` column: - - `json` - - `richText` (Lexical state is a JSON tree). Use `textarea` for multi-line copy and lyrics. - - `blocks` - - `point`, and any delimited or encoded text (no "a,b,c" in a `text` field). +- **Atomic columns only.** These field types are banned in our collections: + - `json`: one `jsonb` column. + - `richText`: Lexical state, one `jsonb` column. Use `textarea` for multi-line copy and lyrics. + - `blocks`: one table per block type hanging off one field, a polymorphic list. Never set `blocksAsJSON` on the adapter either. + - `point`: a PostGIS `geometry` column holding two values. + - `hasMany` on `text` or `number`: stored in generic `_texts` and `_numbers` tables keyed by a text `path`. Use an `array`. + - Any delimited or encoded text (no "a,b,c" in a `text` field). - **Repeating data** is an `array` field. Payload stores it as a child table `_` keyed by parent and order, with a real foreign key. - **Controlled redundancy** is allowed only when the database keeps it consistent, through a constraint or trigger in a hand-written migration. Site code never syncs a redundant value. Every case goes in the register at the end of this file. @@ -32,7 +34,7 @@ Payload generates the Postgres schema from the collection config in `src/collect - **No polymorphic relationships.** `relationTo` is always one collection slug, never an array. - **No `hasMany` on `relationship` or `upload` fields.** Payload stores those in a generic `_rels` table with one nullable column per target and a text `path`, so nothing guarantees a row points where the field says. For many-to-many, use an `array` field holding one single `relationship`, or a join collection with two single relationships. - A single `relationship` or `upload` becomes a `_id` column with a foreign key. That is the only shape we use. -- Check the generated migration: a `_rels` table for one of our collections means a rule was broken. +- Check the generated migration: a `_rels`, `_texts` or `_numbers` table for one of our collections means a rule was broken. ## Languages @@ -46,6 +48,7 @@ Payload generates the Postgres schema from the collection config in `src/collect - A fixed option set that carries only a name is a `select` field. Payload creates a Postgres enum `enum__`; changing the options needs a migration. `hasMany` on a `select` is fine: it becomes a child table of enum values. - A lookup is its own collection, and only when the options carry extra attributes or editors must add options without a deploy. State the reason in the PR. - `required`, `unique` and `index` on a field become `NOT NULL`, a unique index and an index. Use them; they are the first line of integrity. +- Two cases drop the `NOT NULL` silently: a collection with `versions.drafts` on (every required column becomes nullable, because a draft may be incomplete) and a required field with `admin.condition`. Don't put `admin.condition` on a required field. Turning drafts on is a departure: record it in the register. - Numeric ranges and cross-field rules that must hold for direct SQL too go in a `CHECK` constraint in a hand-written migration. Rules that only shape editor input go in the field's `validate`. ## Naming @@ -56,18 +59,18 @@ Payload generates the Postgres schema from the collection config in `src/collect ## Access -- Every collection declares `access` explicitly. Payload's access functions are the only row-level security here. -- `read: () => true` only for content the public site shows. `create`, `update` and `delete` stay at the default (signed-in users). +- Every collection declares `access.read` explicitly, so who can read it is visible in the file. Payload's access functions are the only row-level security here. +- `read: () => true` only for content the public site shows; otherwise `read: ({ req }) => Boolean(req.user)`. Leave `create`, `update` and `delete` unset: Payload's default is signed-in users only. - The `users` collection is never publicly readable. ## Migrations - `src/migrations/` is written by `pnpm exec payload migrate:create ` and applied by `pnpm exec payload migrate`. One concern per migration. -- Read the generated SQL before committing it. Reject `jsonb` columns and `_rels` tables on our collections. -- Hand-written SQL (triggers, functions, `CHECK` constraints, partial indexes) goes in its own blank migration: `pnpm exec payload migrate:create --force-accept-warning`. Never mix it into a generated one. Payload's generator does not know these objects exist, so a later rename can orphan them: list each one in the register below. +- Read the generated SQL before committing it. Reject `jsonb` and `geometry` columns and `_rels`, `_texts` and `_numbers` tables on our collections. +- Hand-written SQL (triggers, functions, `CHECK` constraints, partial indexes) goes in its own blank migration: `pnpm exec payload migrate:create --force-accept-warning`, run when no config change is pending (otherwise the file is not blank). Never mix it into a generated one. The one exception is a rename: Payload generates a drop and an add, which loses data, so replace those statements with `ALTER TABLE … RENAME` in the generated file and say so in the PR. Payload's generator does not know these objects exist, so a later rename can orphan them: list each one in the register below. - Never edit a migration after it has merged. A migration must work with the previous deploy still running. - `pnpm dev` pushes the schema straight to whatever `DATABASE_URL` points at. `.env.local` must point at the Neon `dev` branch, never `preview` or `main`. Those two change only through `payload migrate`. -- `src/payload-types.ts` and `src/app/(payload)/` are generated. Regenerate (`payload generate:types`, `payload generate:importmap`); never hand-edit. Derive every content type in site code from `payload-types.ts`. +- `src/payload-types.ts` and `src/app/(payload)/admin/importMap.js` are generated. Regenerate (`payload generate:types`, `payload generate:importmap`); never hand-edit. The other files in `src/app/(payload)/` were copied in once from Payload's template and are left alone, except `custom.scss`, which is ours to edit. Derive every content type in site code from `payload-types.ts`. ## Uploads @@ -76,7 +79,7 @@ Payload generates the Postgres schema from the collection config in `src/collect ## Proof -There is no test framework. Every constraint, trigger and hand-written index is proven on the Neon `dev` branch with SQL (the `db` method in `docs/tickets/INSTRUCTIONS.md` §3): show that valid data passes and that the misuse it guards against fails. +There is no test framework. Every constraint, trigger and hand-written index is proven on the Neon `preview` branch with SQL (the `db` method in `docs/tickets/INSTRUCTIONS.md` §3), after `payload migrate` has applied it there: show that valid data passes and that the misuse it guards against fails. The `dev` branch cannot be used for this: it only ever receives dev-mode pushes, so migrations never run on it. ## Register of departures diff --git a/.claude/skills/payload-collection/SKILL.md b/.claude/skills/payload-collection/SKILL.md index 6452c39..7771a9d 100644 --- a/.claude/skills/payload-collection/SKILL.md +++ b/.claude/skills/payload-collection/SKILL.md @@ -5,7 +5,7 @@ description: Add or change a Payload collection end to end (config, generated ty # Payload Collection -Changes one collection in `src/collections/`, following `.claude/rules/database.md`. Copy the nearest existing collection (`TourDates.ts` for content, `Media.ts` for uploads) and adapt it. +Changes one collection in `src/collections/`, following `.claude/rules/database.md`. Start from the nearest existing collection (`TourDates.ts` for content, `Media.ts` for uploads) for layout, but the rules win wherever an existing file differs from them: the first collections were written for a spike, before the rules. Every Neon command needs the Tandem profile: `export NEON_PROFILE=tandem`. The `--profile` flag alone is not enough for project-scoped commands. @@ -13,7 +13,8 @@ Every Neon command needs the Tandem profile: `export NEON_PROFILE=tandem`. The ` - `.claude/rules/database.md`, all of it. - The Payload docs for each field type you plan to use, through context7 (`/websites/payloadcms`). Field options change between minor versions. -- `.neon` must say `"branch": "dev"`. If not, run `neon checkout dev` before starting the dev server. +- `pnpm dev` pushes the schema to whatever `DATABASE_URL` in `.env.local` points at, and that must be the Neon `dev` branch. Check without printing a value: `grep -c '^NEON_BRANCH="\?dev"\?$' .env.local` must print `1`. If it prints `0`, run `neon checkout dev`, which rewrites the Neon variables in `.env.local`. +- The admin logins for `dev` and `preview` are not in the repo. `PROMPT.md` (not committed) says where they are; if it doesn't, ask the user. Never reset a branch or a password to get in. ## 1. Design @@ -25,7 +26,7 @@ For each piece of data, decide before writing config: 4. Does it point at another document? Then one `relationship` or `upload` with a single `relationTo` and no `hasMany`. 5. Is it one of a fixed set? Then `select`. -If the answer needs `json`, `richText`, `blocks`, a polymorphic `relationTo` or a `hasMany` relationship, stop and ask. A yes goes in the register in `database.md`. +If the answer needs `json`, `richText`, `blocks`, `point`, a polymorphic `relationTo`, or `hasMany` on a relationship, upload, text or number field, stop and ask. A yes goes in the register in `database.md`. ## 2. Config @@ -36,27 +37,35 @@ If the answer needs `json`, `richText`, `blocks`, a polymorphic `relationTo` or ## 3. Try it on `dev` 1. `pnpm dev --port <4000 + issue number>`. Dev mode pushes the schema to the `dev` branch. + - A change that removes or renames a field makes the push stop and ask `Accept warnings and push schema to database?` in the terminal. A background server then hangs on its first request. For such a change, read the server output for the prompt, tell the user what would be dropped, and run the server in the foreground to answer it only once they agree. 2. In `/admin`, create, edit and delete a document. Read the dev server output for errors. 3. Stop the server by port. ## 4. Migration 1. `pnpm exec payload migrate:create `. -2. Read the generated SQL in `src/migrations/`. It must contain no `jsonb` column and no `_rels` table for our collections, and each relationship must be a `_id` column with a foreign key. +2. Read the generated SQL in `src/migrations/`. It must contain no `jsonb` or `geometry` column and no `_rels`, `_texts` or `_numbers` table for our collections, and each relationship must be a `_id` column with a foreign key. 3. A rename shows up as drop and add, which loses data. Write the `ALTER TABLE … RENAME` by hand in that migration instead and say so in the PR. ## 5. Hand-written objects Only when a rule must hold for direct SQL too. -1. `pnpm exec payload migrate:create --force-accept-warning` writes a blank migration. Put the SQL in `up` and its reverse in `down`, using `db.execute(sql\`…\`)`. +1. With no config change pending, `pnpm exec payload migrate:create --force-accept-warning` writes a blank migration. Put the SQL in `up` and its reverse in `down`, using `db.execute(sql\`…\`)`. 2. Functions set `search_path` explicitly and are not `SECURITY DEFINER` unless they must be. 3. Add the object to the register in `database.md`. ## 6. Apply to `preview` and prove 1. Pull the `preview` branch's variables to a file outside the working tree: `neon env pull --branch preview --file .git/ticket//artefacts/preview.env`. Never print it. -2. With `.env.local` and then that file loaded into the shell, run `pnpm exec payload migrate`. +2. Load that file into a subshell and check the target before migrating. Payload's CLI reads `.env.local` by itself, so if the file fails to load, the command silently runs against `dev`: + + ```bash + (set -a; . .git/ticket//artefacts/preview.env; set +a + echo "$NEON_BRANCH" # must print: preview + pnpm exec payload migrate:status + pnpm exec payload migrate) + ``` 3. Prove with SQL through `neon psql preview -- -Atc ""`: the table and columns exist, valid data passes, and each constraint rejects what it guards against. Keep the output for the PR. 4. After the PR's deploy preview is ready, create a document in the preview's admin and load the page that shows it. From 300b170ad32660bf4a502a97af34f985605832a0 Mon Sep 17 00:00:00 2001 From: maxitect Date: Thu, 12 Nov 2026 20:26:20 +0000 Subject: [PATCH 08/17] docs(tickets): describe neon branches, preview variables and db proof --- docs/tickets/INSTRUCTIONS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/tickets/INSTRUCTIONS.md b/docs/tickets/INSTRUCTIONS.md index c1f4aeb..d5f0014 100644 --- a/docs/tickets/INSTRUCTIONS.md +++ b/docs/tickets/INSTRUCTIONS.md @@ -53,7 +53,7 @@ State lives in `.git/ticket/`, outside the working tree: per ticket, `env` (the | `cli` | A command's result | Run it | The command, its output and exit code | | `code` | A structural rule ("no request to X", "no hard-coded Y") | `grep` or reading | The command and its output | | `deploy` | Anything that depends on Netlify: headers, caching, redirects, functions, environment variables, images, the adapter | The PR's deploy preview, `https://deploy-preview---clarksbowlingclub.netlify.app`, once `gh pr checks` shows it ready | The URL, the command and its output | -| `db` | Payload and Postgres, once they exist | SQL on the local database or a Neon preview branch, never production | The SQL and its output | +| `db` | Payload and Postgres | SQL on the Neon `dev` or `preview` branch (`neon psql -- -Atc ""`), never `main` | The SQL and its output | | `mail` | The contact form | A local SMTP catcher in place of the real mailbox (§4) | The captured message's headers and body | Rules: @@ -73,7 +73,7 @@ One checkout, one ticket in flight at a time. | Package manager | pnpm. Never npm or yarn | | Dev server | `pnpm dev --port <4000 + issue number>`, e.g. ticket 27 uses 4027. Run it in the background and stop it when you're done | | The user's own server | Port 3000 belongs to the user. Never use it, never stop it | -| Env file | `.env.local` in the repo root. Read variable names only | +| Env file | `.env.local` in the repo root. Read variable names only. Its `DATABASE_URL` must point at the Neon `dev` branch: `pnpm dev` pushes the Payload schema to it | | Content | The published Google Sheet, read as CSV by `src/utils/fetchSheet.ts`, until Payload replaces it | | Artefacts | Screenshots, logs and scratch scripts go in `.git/ticket//artefacts/`, never in the working tree | @@ -128,10 +128,10 @@ The Netlify, Neon and GitHub tools are installed and signed in. Use them to find | Deploy previews | One per PR, at `https://deploy-preview---clarksbowlingclub.netlify.app`. `gh pr checks ` shows when it is ready | | Build | `@netlify/plugin-nextjs`; settings are in the Netlify UI until `netlify.toml` lands (#26) | | Free plan limits | 100 GB bandwidth, 300 build minutes and 125,000 function calls a month. Each push to a PR costs a build, so push as few times as you can | -| Environment variables | `EMAIL_HOST`, `EMAIL_PORT`, `EMAIL_SECURE`, `EMAIL_USER`, `EMAIL_PASSWORD` (secret), `NEXT_PUBLIC_CSV_URL` | +| Environment variables | All contexts: `EMAIL_HOST`, `EMAIL_PORT`, `EMAIL_SECURE`, `EMAIL_USER`, `EMAIL_PASSWORD` (secret), `NEXT_PUBLIC_CSV_URL`. Deploy previews only, until the migration: `DATABASE_URL`, `PAYLOAD_SECRET`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` (secrets), `S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET`. Netlify reserves the `AWS_*` names, so Neon's storage credentials are stored as `S3_*` | | Database | Neon project `cbc` (`damp-truth-56586096`), Frankfurt, free plan, in the Tandem Neon account: run Neon commands with `NEON_PROFILE=tandem`. Branches: `main` (production, empty until the migration), `preview` (shared by every deploy preview), `dev` (local). Bucket `media` on each branch. Spiked in #32; migration in #33 | -Reads are always fine: deploy logs (`netlify api getDeploy`, `listSiteDeploys`), variable names, DNS lookups. Anything that changes a hosted service needs the user's approval first; agents ask the `/tickets` driver, and the driver asks the user. +Reads are always fine: deploy logs (`netlify api getDeploy`, `listSiteDeploys`), variable names, DNS lookups. Anything that changes a hosted service needs the user's approval first; agents ask the `/tickets` driver, and the driver asks the user. The one standing exception is the Neon `dev` and `preview` branches: a ticket may push schema to `dev`, run `payload migrate` on `preview` and create test content on either. Resetting or deleting a branch still needs approval, and `main` is never written. ## 8. The codebase in brief From 8bd60ba0d77d757777493afee23ec69dcb9212c3 Mon Sep 17 00:00:00 2001 From: maxitect Date: Thu, 12 Nov 2026 20:39:04 +0000 Subject: [PATCH 09/17] feat(data): add cached readers for sheet content --- src/lib/data/content.ts | 54 +++++++++++++++++++++++++++++++++++++++++ src/utils/gigTime.ts | 6 +++++ 2 files changed, 60 insertions(+) create mode 100644 src/lib/data/content.ts create mode 100644 src/utils/gigTime.ts diff --git a/src/lib/data/content.ts b/src/lib/data/content.ts new file mode 100644 index 0000000..152b507 --- /dev/null +++ b/src/lib/data/content.ts @@ -0,0 +1,54 @@ +import { cacheLife } from "next/cache"; +import fetchSheet from "@/utils/fetchSheet"; +import parseCsv from "@/utils/parseCsv"; +import parsePageCsv from "@/utils/parsePageCsv"; +import { IFrameProps, LyricsProps, Page, TourDateType } from "@/utils/types"; + +export interface BilingualPage { + french: Page; + english: Page; +} + +async function getPage(tabGid: number): Promise { + const [french, english] = parsePageCsv(await fetchSheet(tabGid)); + return { french, english }; +} + +export async function getAboutPage(): Promise { + "use cache"; + cacheLife("minutes"); + return getPage(0); +} + +export async function getTourPage(): Promise { + "use cache"; + cacheLife("minutes"); + return getPage(127405583); +} + +export async function getTourDates(): Promise { + "use cache"; + cacheLife("minutes"); + return parseCsv( + await fetchSheet(572869052), + (row) => !!row.eventDate + ); +} + +export async function getMusicItems(): Promise { + "use cache"; + cacheLife("minutes"); + return parseCsv( + await fetchSheet(1713768433), + (row) => !!row.title && !!row.type + ); +} + +export async function getLyrics(): Promise { + "use cache"; + cacheLife("minutes"); + return parseCsv( + await fetchSheet(145198726), + (row) => !!row.title && !!row.lyrics + ); +} diff --git a/src/utils/gigTime.ts b/src/utils/gigTime.ts new file mode 100644 index 0000000..5b69127 --- /dev/null +++ b/src/utils/gigTime.ts @@ -0,0 +1,6 @@ +import { TourDateType } from "./types"; + +export default function gigTime(gig: TourDateType): number { + const [day, month, year] = gig.eventDate.split("/").map(Number); + return new Date(year, month - 1, day).getTime(); +} From d2c9ab7b2ac93b02738b3d9215015d6297c7d24b Mon Sep 17 00:00:00 2001 From: maxitect Date: Thu, 12 Nov 2026 20:39:10 +0000 Subject: [PATCH 10/17] feat(pages): read sheet content on the server and pass it as props --- .../about/_components/AboutClient.tsx | 30 ++------- src/app/(frontend)/about/page.tsx | 5 +- .../lyrics/_components/LyricsClient.tsx | 43 ++---------- src/app/(frontend)/lyrics/page.tsx | 5 +- .../music/_components/MusicClient.tsx | 65 ++++-------------- src/app/(frontend)/music/page.tsx | 5 +- .../tour/_components/TourClient.tsx | 67 +++---------------- .../tour/_components/TourDatesLists.tsx | 30 +++++++++ src/app/(frontend)/tour/page.tsx | 30 ++++++++- 9 files changed, 101 insertions(+), 179 deletions(-) create mode 100644 src/app/(frontend)/tour/_components/TourDatesLists.tsx diff --git a/src/app/(frontend)/about/_components/AboutClient.tsx b/src/app/(frontend)/about/_components/AboutClient.tsx index e56a68e..a896ac6 100644 --- a/src/app/(frontend)/about/_components/AboutClient.tsx +++ b/src/app/(frontend)/about/_components/AboutClient.tsx @@ -1,11 +1,9 @@ "use client"; -import { useEffect, useState } from "react"; +import { useEffect } from "react"; import { useLanguage } from "@/context/LanguageContext"; -import { Page } from "@/utils/types"; import Carousel from "@/components/ui/Carousel"; -import parsePageCsv from "@/utils/parsePageCsv"; -import fetchSheet from "@/utils/fetchSheet"; +import { BilingualPage } from "@/lib/data/content"; const carouselImages = [ "/images/carousel/argentic.jpg", @@ -19,29 +17,9 @@ const carouselAlts = [ "Band leaving the warehouse after rehearsal and shoot", "Still of the band in Yes Day music video shoot", ]; -const sheetTabGid = 0; - -export default function AboutClient() { +export default function AboutClient({ french, english }: BilingualPage) { const { isFrench } = useLanguage(); - const [englishContent, setEnglishContent] = useState(null); - const [frenchContent, setFrenchContent] = useState(null); - - useEffect(() => { - const fetchContent = async () => { - try { - const csvData = await fetchSheet(sheetTabGid); - const parsedContent = parsePageCsv(csvData); - setEnglishContent(parsedContent[1]); - setFrenchContent(parsedContent[0]); - } catch (error) { - console.error("Error fetching or parsing page content:", error); - } - }; - - fetchContent(); - }, []); - - const pageContent = isFrench ? frenchContent : englishContent; + const pageContent = isFrench ? french : english; useEffect(() => { document.title = `${isFrench ? "Bio" : "About"} | Clark's Bowling Club`; diff --git a/src/app/(frontend)/about/page.tsx b/src/app/(frontend)/about/page.tsx index e31ebd8..da1f4b5 100644 --- a/src/app/(frontend)/about/page.tsx +++ b/src/app/(frontend)/about/page.tsx @@ -1,10 +1,11 @@ import type { Metadata } from "next"; +import { getAboutPage } from "@/lib/data/content"; import AboutClient from "./_components/AboutClient"; export const metadata: Metadata = { title: "About", }; -export default function AboutPage() { - return ; +export default async function AboutPage() { + return ; } diff --git a/src/app/(frontend)/lyrics/_components/LyricsClient.tsx b/src/app/(frontend)/lyrics/_components/LyricsClient.tsx index 40815ba..35ea259 100644 --- a/src/app/(frontend)/lyrics/_components/LyricsClient.tsx +++ b/src/app/(frontend)/lyrics/_components/LyricsClient.tsx @@ -1,49 +1,20 @@ "use client"; import { useLanguage } from "@/context/LanguageContext"; -import fetchSheet from "@/utils/fetchSheet"; -import parseCsv from "@/utils/parseCsv"; import { useEffect, useState } from "react"; import clsx from "clsx"; import { LyricsProps } from "@/utils/types"; import FilterNavigation from "@/components/layout/FilterNavigation"; -const sheetTabGid = 145198726; - -export default function LyricsClient() { +export default function LyricsClient({ lyrics }: { lyrics: LyricsProps[] }) { const { isFrench } = useLanguage(); - const [lyrics, setLyrics] = useState([]); - const [albums, setAlbums] = useState([]); - const [selectedAlbum, setSelectedAlbum] = useState(); + const [pickedAlbum, setPickedAlbum] = useState(); const [pickedSong, setPickedSong] = useState(); - useEffect(() => { - const fetchContent = async () => { - try { - const csvData = await fetchSheet(sheetTabGid); - const parsedData: LyricsProps[] = parseCsv( - csvData, - (row) => !!row.title && !!row.lyrics - ); - - console.log("Parsed Lyrics Content:", parsedData); - setLyrics(parsedData); - - const uniqueAlbums = Array.from( - new Set(parsedData.map((item) => item.album || "")) - ).filter(Boolean); - - setAlbums(uniqueAlbums); - if (uniqueAlbums.length > 0) { - setSelectedAlbum(uniqueAlbums[0]); - } - } catch (error) { - console.error("Error fetching or parsing music content:", error); - } - }; - - fetchContent(); - }, [isFrench]); + const albums = Array.from( + new Set(lyrics.map((item) => item.album || "")) + ).filter(Boolean); + const selectedAlbum = pickedAlbum ?? albums[0]; const filteredSongs = selectedAlbum ? lyrics.filter((song) => song.album === selectedAlbum) @@ -68,7 +39,7 @@ export default function LyricsClient() { : `Showing lyrics for ${selectedSong.title}`; const handleAlbumChange = (album: string) => { - setSelectedAlbum(album); + setPickedAlbum(album); }; const handleSongSelect = (song: LyricsProps) => { diff --git a/src/app/(frontend)/lyrics/page.tsx b/src/app/(frontend)/lyrics/page.tsx index d4a4ff6..a24edc8 100644 --- a/src/app/(frontend)/lyrics/page.tsx +++ b/src/app/(frontend)/lyrics/page.tsx @@ -1,10 +1,11 @@ import type { Metadata } from "next"; +import { getLyrics } from "@/lib/data/content"; import LyricsClient from "./_components/LyricsClient"; export const metadata: Metadata = { title: "Lyrics", }; -export default function LyricsPage() { - return ; +export default async function LyricsPage() { + return ; } diff --git a/src/app/(frontend)/music/_components/MusicClient.tsx b/src/app/(frontend)/music/_components/MusicClient.tsx index 6e53aba..24a73ef 100644 --- a/src/app/(frontend)/music/_components/MusicClient.tsx +++ b/src/app/(frontend)/music/_components/MusicClient.tsx @@ -5,62 +5,25 @@ import Youtube from "./Youtube"; import Spotify from "./Spotify"; import { useLanguage } from "@/context/LanguageContext"; import { IFrameProps } from "@/utils/types"; -import fetchSheet from "@/utils/fetchSheet"; -import parseCsv from "@/utils/parseCsv"; import { useEffect, useState } from "react"; import FilterNavigation from "@/components/layout/FilterNavigation"; -const sheetTabGid = 1713768433; - -export default function MusicClient() { +export default function MusicClient({ iFrames }: { iFrames: IFrameProps[] }) { const { isFrench } = useLanguage(); - const [iFrames, setIFrames] = useState([]); - const [categories, setCategories] = useState([]); - const [selectedCategory, setSelectedCategory] = useState< - string | number | readonly string[] | undefined - >("Live Performances"); - - useEffect(() => { - const fetchContent = async () => { - try { - const csvData = await fetchSheet(sheetTabGid); - const parsedData: IFrameProps[] = parseCsv( - csvData, - (row) => !!row.title && !!row.type - ); - - console.log("Parsed Music Content:", parsedData); - setIFrames(parsedData); - - const categoryKey = isFrench ? "categorie" : "category"; - const uniqueCategories = Array.from( - new Set( - parsedData.map( - (item) => item[categoryKey as keyof IFrameProps] || "" - ) - ) - ); + const [pickedCategory, setPickedCategory] = useState(); - setCategories(uniqueCategories); - if (uniqueCategories.length > 0) { - setSelectedCategory(uniqueCategories[0]); - } - } catch (error) { - console.error("Error fetching or parsing music content:", error); - } - }; - - fetchContent(); - }, [isFrench]); + const categoryKey = isFrench ? "categorie" : "category"; + const categories = Array.from( + new Set(iFrames.map((item) => item[categoryKey] || "")) + ); + const selectedCategory = + pickedCategory !== undefined && categories.includes(pickedCategory) + ? pickedCategory + : categories[0]; - const filteredIFrames = - selectedCategory === null - ? [] - : iFrames.filter( - (item) => - item[(isFrench ? "categorie" : "category") as keyof IFrameProps] === - selectedCategory - ); + const filteredIFrames = iFrames.filter( + (item) => (item[categoryKey] || "") === selectedCategory + ); useEffect(() => { document.title = `${isFrench ? "Musique" : "Music"} | Clark's Bowling Club`; @@ -71,7 +34,7 @@ export default function MusicClient() { : `${filteredIFrames.length} items in category ${selectedCategory}`; const handleCategoryChange = (category: string) => { - setSelectedCategory(category); + setPickedCategory(category); }; if (iFrames.length === 0) diff --git a/src/app/(frontend)/music/page.tsx b/src/app/(frontend)/music/page.tsx index 63d8cbf..ec071fc 100644 --- a/src/app/(frontend)/music/page.tsx +++ b/src/app/(frontend)/music/page.tsx @@ -1,10 +1,11 @@ import type { Metadata } from "next"; +import { getMusicItems } from "@/lib/data/content"; import MusicClient from "./_components/MusicClient"; export const metadata: Metadata = { title: "Music", }; -export default function MusicPage() { - return ; +export default async function MusicPage() { + return ; } diff --git a/src/app/(frontend)/tour/_components/TourClient.tsx b/src/app/(frontend)/tour/_components/TourClient.tsx index e1f1575..22c0c9c 100644 --- a/src/app/(frontend)/tour/_components/TourClient.tsx +++ b/src/app/(frontend)/tour/_components/TourClient.tsx @@ -1,63 +1,21 @@ "use client"; -import { useEffect, useState } from "react"; +import { ReactNode, useEffect } from "react"; import { useLanguage } from "@/context/LanguageContext"; -import { Page, TourDateType } from "@/utils/types"; -import fetchSheet from "@/utils/fetchSheet"; -import parseCsv from "@/utils/parseCsv"; -import parsePageCsv from "@/utils/parsePageCsv"; -import dateInPast from "@/utils/dateInPast"; -import TourDatesContainer from "./TourDatesContainer"; +import { BilingualPage } from "@/lib/data/content"; -const sheetTabGid = 127405583; // Main Tour page content -const sheetTabGidTourDates = 572869052; // Tour dates - -function gigTime(gig: TourDateType): number { - const [day, month, year] = gig.eventDate.split("/").map(Number); - return new Date(year, month - 1, day).getTime(); -} - -export default function TourClient() { +export default function TourClient({ + french, + english, + children, +}: BilingualPage & { children: ReactNode }) { const { isFrench } = useLanguage(); - const [englishContent, setEnglishContent] = useState(null); - const [frenchContent, setFrenchContent] = useState(null); - const [gigs, setGigs] = useState([]); - - useEffect(() => { - const fetchContent = async () => { - try { - const pageCsvData = await fetchSheet(sheetTabGid); - const parsedPageContent = parsePageCsv(pageCsvData); - setEnglishContent(parsedPageContent[1]); - setFrenchContent(parsedPageContent[0]); - - const tourDatesCsvData = await fetchSheet(sheetTabGidTourDates); - const parsedGigs = parseCsv( - tourDatesCsvData, - (row) => !!row.eventDate - ); - setGigs(parsedGigs); - } catch (error) { - console.error("Error fetching or parsing content:", error); - } - }; - - fetchContent(); - }, []); - - const pageContent = isFrench ? frenchContent : englishContent; + const pageContent = isFrench ? french : english; useEffect(() => { document.title = `${isFrench ? "Tournée" : "Tour"} | Clark's Bowling Club`; }, [isFrench]); - const pastGigs = gigs - .filter((gig) => dateInPast(gig.eventDate)) - .sort((a, b) => gigTime(b) - gigTime(a)); - const futureGigs = gigs - .filter((gig) => !dateInPast(gig.eventDate)) - .sort((a, b) => gigTime(a) - gigTime(b)); - if (!pageContent) return (
@@ -72,14 +30,7 @@ export default function TourClient() { <>

{pageContent.title}

{pageContent.content}

- - + {children} ); } diff --git a/src/app/(frontend)/tour/_components/TourDatesLists.tsx b/src/app/(frontend)/tour/_components/TourDatesLists.tsx new file mode 100644 index 0000000..1e67a6e --- /dev/null +++ b/src/app/(frontend)/tour/_components/TourDatesLists.tsx @@ -0,0 +1,30 @@ +"use client"; + +import { useLanguage } from "@/context/LanguageContext"; +import { TourDateType } from "@/utils/types"; +import TourDatesContainer from "./TourDatesContainer"; + +interface TourDatesListsProps { + futureGigs: TourDateType[]; + pastGigs: TourDateType[]; +} + +export default function TourDatesLists({ + futureGigs, + pastGigs, +}: TourDatesListsProps) { + const { isFrench } = useLanguage(); + + return ( + <> + + + + ); +} diff --git a/src/app/(frontend)/tour/page.tsx b/src/app/(frontend)/tour/page.tsx index b57087e..f729c3f 100644 --- a/src/app/(frontend)/tour/page.tsx +++ b/src/app/(frontend)/tour/page.tsx @@ -1,10 +1,36 @@ +import { Suspense } from "react"; import type { Metadata } from "next"; +import { connection } from "next/server"; +import { getTourDates, getTourPage } from "@/lib/data/content"; +import dateInPast from "@/utils/dateInPast"; +import gigTime from "@/utils/gigTime"; import TourClient from "./_components/TourClient"; +import TourDatesLists from "./_components/TourDatesLists"; export const metadata: Metadata = { title: "Tour", }; -export default function TourPage() { - return ; +async function TourDates() { + const gigs = await getTourDates(); + await connection(); + + const pastGigs = gigs + .filter((gig) => dateInPast(gig.eventDate)) + .sort((a, b) => gigTime(b) - gigTime(a)); + const futureGigs = gigs + .filter((gig) => !dateInPast(gig.eventDate)) + .sort((a, b) => gigTime(a) - gigTime(b)); + + return ; +} + +export default async function TourPage() { + return ( + + + + + + ); } From 001183e11517fe6938c80739acad75003d9ce39b Mon Sep 17 00:00:00 2001 From: maxitect Date: Thu, 12 Nov 2026 20:39:15 +0000 Subject: [PATCH 11/17] refactor(routes): reuse cached readers in sitemap, llms.txt and markdown pages --- src/app/(frontend)/[...slug]/route.ts | 45 ++++++++++----------------- src/app/(frontend)/llms.txt/route.ts | 37 +++++++++------------- src/app/sitemap.ts | 24 ++++---------- 3 files changed, 37 insertions(+), 69 deletions(-) diff --git a/src/app/(frontend)/[...slug]/route.ts b/src/app/(frontend)/[...slug]/route.ts index d57a34f..6d21ee9 100644 --- a/src/app/(frontend)/[...slug]/route.ts +++ b/src/app/(frontend)/[...slug]/route.ts @@ -1,8 +1,11 @@ import { NextRequest } from "next/server"; -import fetchSheet from "@/utils/fetchSheet"; -import parsePageCsv from "@/utils/parsePageCsv"; -import parseCsv from "@/utils/parseCsv"; -import { IFrameProps, LyricsProps, TourDateType } from "@/utils/types"; +import { + getAboutPage, + getLyrics, + getMusicItems, + getTourDates, + getTourPage, +} from "@/lib/data/content"; export async function GET( request: NextRequest, @@ -50,12 +53,11 @@ async function generatePageMarkdown(page: string): Promise { case "about": try { - const aboutData = await fetchSheet(0); - const aboutContent = parsePageCsv(aboutData); - if (aboutContent[1]) { - sections.push(`# ${aboutContent[1].title}`); + const { english: aboutEnglish } = await getAboutPage(); + if (aboutEnglish) { + sections.push(`# ${aboutEnglish.title}`); sections.push(""); - sections.push(aboutContent[1].content); + sections.push(aboutEnglish.content); } } catch { return null; @@ -66,11 +68,7 @@ async function generatePageMarkdown(page: string): Promise { sections.push("# Music"); sections.push(""); try { - const musicData = await fetchSheet(1713768433); - const musicItems = parseCsv( - musicData, - (row) => !!row.title && !!row.type - ); + const musicItems = await getMusicItems(); const categories = [ ...new Set( @@ -103,18 +101,13 @@ async function generatePageMarkdown(page: string): Promise { sections.push("# Tour"); sections.push(""); try { - const tourPageData = await fetchSheet(127405583); - const tourPageContent = parsePageCsv(tourPageData); - if (tourPageContent[1]?.content) { - sections.push(tourPageContent[1].content); + const { english: tourEnglish } = await getTourPage(); + if (tourEnglish?.content) { + sections.push(tourEnglish.content); sections.push(""); } - const tourData = await fetchSheet(572869052); - const tourItems = parseCsv( - tourData, - (row) => !!row.eventDate - ); + const tourItems = await getTourDates(); const now = new Date(); const futureGigs = tourItems.filter((gig) => { @@ -163,11 +156,7 @@ async function generatePageMarkdown(page: string): Promise { sections.push("# Lyrics"); sections.push(""); try { - const lyricsData = await fetchSheet(145198726); - const lyricsItems = parseCsv( - lyricsData, - (row) => !!row.title && !!row.lyrics - ); + const lyricsItems = await getLyrics(); const albums = [ ...new Set(lyricsItems.map((item) => item.album).filter(Boolean)), diff --git a/src/app/(frontend)/llms.txt/route.ts b/src/app/(frontend)/llms.txt/route.ts index f616930..157fba0 100644 --- a/src/app/(frontend)/llms.txt/route.ts +++ b/src/app/(frontend)/llms.txt/route.ts @@ -1,9 +1,13 @@ -import fetchSheet from "@/utils/fetchSheet"; -import parsePageCsv from "@/utils/parsePageCsv"; -import parseCsv from "@/utils/parseCsv"; -import { IFrameProps, LyricsProps, TourDateType } from "@/utils/types"; +import { connection } from "next/server"; +import { + getAboutPage, + getLyrics, + getMusicItems, + getTourDates, +} from "@/lib/data/content"; export async function GET() { + await connection(); try { const content = await generateLLMsTxt(); @@ -31,10 +35,9 @@ async function generateLLMsTxt(): Promise { sections.push("## About"); try { - const aboutData = await fetchSheet(0); - const aboutContent = parsePageCsv(aboutData); - if (aboutContent[1]?.content) { - sections.push(aboutContent[1].content); + const { english: aboutEnglish } = await getAboutPage(); + if (aboutEnglish?.content) { + sections.push(aboutEnglish.content); sections.push(""); } } catch (error) { @@ -43,11 +46,7 @@ async function generateLLMsTxt(): Promise { sections.push("## Music"); try { - const musicData = await fetchSheet(1713768433); - const musicItems = parseCsv( - musicData, - (row) => !!row.title && !!row.type - ); + const musicItems = await getMusicItems(); const categories = [ ...new Set( @@ -73,11 +72,7 @@ async function generateLLMsTxt(): Promise { sections.push("## Tour Dates"); try { - const tourData = await fetchSheet(572869052); - const tourItems = parseCsv( - tourData, - (row) => !!row.eventDate - ); + const tourItems = await getTourDates(); const now = new Date(); const futureGigs = tourItems @@ -115,11 +110,7 @@ async function generateLLMsTxt(): Promise { sections.push("## Lyrics"); try { - const lyricsData = await fetchSheet(145198726); - const lyricsItems = parseCsv( - lyricsData, - (row) => !!row.title && !!row.lyrics - ); + const lyricsItems = await getLyrics(); const albums = [ ...new Set(lyricsItems.map((item) => item.album).filter(Boolean)), diff --git a/src/app/sitemap.ts b/src/app/sitemap.ts index afc2320..b5a07d5 100644 --- a/src/app/sitemap.ts +++ b/src/app/sitemap.ts @@ -1,12 +1,12 @@ import { MetadataRoute } from "next"; -import fetchSheet from "@/utils/fetchSheet"; -import parseCsv from "@/utils/parseCsv"; -import { IFrameProps, LyricsProps, TourDateType } from "@/utils/types"; +import { connection } from "next/server"; +import { getLyrics, getMusicItems, getTourDates } from "@/lib/data/content"; const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL || "https://clarksbowlingclub.com"; export default async function sitemap(): Promise { + await connection(); const staticPages = [ { url: SITE_URL, @@ -55,11 +55,7 @@ async function getDynamicPages(): Promise { const pages: MetadataRoute.Sitemap = []; try { - const musicData = await fetchSheet(1713768433); - const musicItems = parseCsv( - musicData, - (row) => !!row.title && !!row.type - ); + const musicItems = await getMusicItems(); if (musicItems.length > 0) { pages.push({ url: `${SITE_URL}/music`, @@ -69,11 +65,7 @@ async function getDynamicPages(): Promise { }); } - const lyricsData = await fetchSheet(145198726); - const lyricsItems = parseCsv( - lyricsData, - (row) => !!row.title && !!row.lyrics - ); + const lyricsItems = await getLyrics(); if (lyricsItems.length > 0) { pages.push({ url: `${SITE_URL}/lyrics`, @@ -83,11 +75,7 @@ async function getDynamicPages(): Promise { }); } - const tourData = await fetchSheet(572869052); - const tourItems = parseCsv( - tourData, - (row) => !!row.eventDate - ); + const tourItems = await getTourDates(); if (tourItems.length > 0) { pages.push({ url: `${SITE_URL}/tour`, From 753ec9d9a45438c1860004a908ada6d762afc048 Mon Sep 17 00:00:00 2001 From: maxitect Date: Thu, 12 Nov 2026 20:39:20 +0000 Subject: [PATCH 12/17] feat(config): enable cache components and read the sheet url server-side --- next.config.ts | 2 +- src/app/(frontend)/layout.tsx | 5 ++++- src/utils/fetchSheet.ts | 13 ++++--------- 3 files changed, 9 insertions(+), 11 deletions(-) diff --git a/next.config.ts b/next.config.ts index e9ffa30..584cbfc 100644 --- a/next.config.ts +++ b/next.config.ts @@ -1,7 +1,7 @@ import type { NextConfig } from "next"; const nextConfig: NextConfig = { - /* config options here */ + cacheComponents: true, }; export default nextConfig; diff --git a/src/app/(frontend)/layout.tsx b/src/app/(frontend)/layout.tsx index f2277fb..0ebf390 100644 --- a/src/app/(frontend)/layout.tsx +++ b/src/app/(frontend)/layout.tsx @@ -1,3 +1,4 @@ +import { Suspense } from "react"; import type { Metadata } from "next"; import "./globals.css"; import Header from "@/components/layout/Header"; @@ -66,7 +67,9 @@ export default function RootLayout({ {children} -