poetic-fiddle

A user-friendly interface to the Poetic poem-authoring framework.

Live at: https://www.poeticfiddle.com/

Environment & secrets

No live Supabase project currently backs the deployed app (issue #418) — it runs in the degraded mode issue #422 describes: the editor and live preview work as normal, and sign-in, saving and sharing show an "unavailable right now" state instead of failing outright. See docs/IMPLEMENTATION-PLAN.md §6.3.

The app reads its configuration from environment variables. .env.example lists every variable the app expects, with comments on which are public and which are server-only secrets — it is the contract to code against and holds no real values.

• Local development: copy .env.example to .env.local (git-ignored) and fill in real values. You can either use a live Supabase cloud project (described below), or run a fully local dev database with supabase start.
• Local-only Supabase (zero-cloud dev loop): run supabase start to spin up a local Postgres database with migrations applied. supabase start prints the local Supabase URL and anon key to your terminal — copy these into .env.local as NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY, then npm run dev. This dev loop is fully local and does not require a live Supabase account.
• Cloud Supabase project (for testing against production schema): fill in .env.local from your project's Supabase dashboard (Project Settings → API). Do this before running npm run dev — without it, the editor pane fails to load in the browser (an on-screen message explains what to do).
• Deployed app (Vercel): set the same variables under the project's Environment Variables, scoped per environment. Keep the service-role key as a server-only secret; never expose it to the browser. For how code reaches production and how to roll back a bad deploy, see docs/RELEASE-RUNBOOK.md's "Deployment and rollback".

Variables prefixed NEXT_PUBLIC_ are inlined into the browser bundle at build time, so only values designed to be public — the Supabase URL and anon key, guarded by Row-Level Security — may use that prefix. Server-only secrets (such as the service-role key) must not.

CI (GitHub Actions): Committed migrations are tested on every pull request that touches supabase/migrations/ by the database job, which applies them to a throwaway local Supabase instance and runs the pgTAP suite via supabase test db (see npm run test:db in the Development section above). The deploy job, which pushes migrations to a live Supabase project on merge to main, is currently disabled (if: false) because no live project exists — the Supabase organisation dropped to the free plan and deleted the project (issue #418, #422). If a live project is restored, the job can be re-enabled to push committed migrations automatically to production, authenticating with two repo secrets (Settings → Secrets and variables → Actions): SUPABASE_ACCESS_TOKEN (Supabase dashboard → Account → Access Tokens) and SUPABASE_DB_PASSWORD (Project Settings → Database).

Backups

The Supabase project ran on the organisation's Pro plan, which includes automatic daily backups with 7 days' retention by default and Point-in-Time Recovery as a separate paid add-on (not enabled for this project) — but no live project currently exists: the organisation dropped back to the free plan and the project was deleted (see issue #418/#422). See docs/PRIVACY-EXPORT-DELETE-RUNBOOK.md for the full guarantee, its restore procedure, and how to fulfil a poet's export/delete request.

Development

Requires Node.js 22.x. Install dependencies with npm install, then:

Command	Purpose
npm run dev	Start the dev server at http://localhost:3000
npm start	Serve a production build made with npm run build
npm run build	Production build
npm run lint	ESLint
npm run typecheck	TypeScript, no emit
npm run format / format:check	Prettier
npm test	Vitest
npm run test:watch	Vitest in watch mode
npm run coverage	Vitest with coverage reporting
npm run test:a11y	Real-browser axe-core accessibility checks against a production build, via Playwright (npx playwright install chromium first)
npm run test:db	pgTAP data-layer tests, via the Supabase CLI (supabase start first)

On WSL, npm/node commands can pick up the Windows binaries ahead of the Linux ones on PATH. scripts/setup-linux.sh loads nvm first so the Linux toolchain is used instead — prefix any npm run … command with it, e.g. ./scripts/setup-linux.sh npm run build.