Contributing

Thanks for helping. Posy is small on purpose: a beautiful page, a calm editor, agents that can edit it. Before adding a feature, ask whether it makes the page more beautiful or the editor simpler. Please follow the Code of Conduct. To report a security problem, see SECURITY.md and do not open a public issue.

Setup

npm install
npm run dev          # http://localhost:3000 (sign up; the first account owns the instance)

Before you open a PR

npm run check        # TypeScript + example pages validate
npm test             # unit tests (Vitest)
npm run e2e          # sign-up to publish, API keys, MCP (Playwright; builds and starts its own server)
npm run build        # production build

The end-to-end tests use a throwaway database in .scratch/e2e-data, never your real data. Stop npm run dev first (one Next server per folder).

Where things live

Path	What
`src/lib/schema.ts`	The page format (Zod). Run `npm run schema` after changing it.
`src/lib/themes.ts`	Theme tokens. Every theme defines the same six pastel tints.
`src/lib/platforms.ts`	Social platforms and their icons (Simple Icons).
`src/lib/detect.ts`	Turns a pasted link into the right tile.
`src/components/page/`	The public page. Server components plus small client islands.
`src/components/studio/`	The editor (Zustand store, dnd-kit, shadcn/ui).
`src/app/api/`	Auth, REST (`v1`), hosted MCP (`mcp`), uploads, tracking.
`src/edition/`	What an instance allows (self-hosted vs hosted platform).
`src/db/`	Drizzle schema; migrations in `drizzle/`.

Adding a platform or a tile type

Platform: add it to PLATFORMS with its icon, hosts and URL pattern, then add a case to tests/unit/detect.test.ts.
Tile type: add a schema entry, a view in tiles.tsx, fields in TileControls.tsx, then run npm run schema.

Adding a look

A look (the style of a page) is a set of components that draw the same tiles their own way. Offer six at most; minimal stays only as the hidden fallback. Touch these files, in this order:

src/lib/schema.ts: add the id to STYLES (and to BASE_FONTS if it has its own font pair).
src/lib/styles.ts: add it to STYLE_INFO (label, one-line note, default preset, font and layout), to STYLE_IDS (the order people see) and to STYLE_PALETTES (four palettes, the first is the default).
src/lib/style.ts: add its font pair to FONT_PAIRS.
src/lib/themes.ts: add the palettes. Every theme defines every token.
src/lib/fonts.ts: declare the fonts the pair uses (next/font needs literal options).
src/lib/templates.ts: write the starter page and add it to STYLE_STARTERS.
src/components/page/styles/<id>.tsx and <id>.css: Header, Tile and Row. A scene (moving background) goes in <id>-scene.tsx and .css. Register all of it in styles/index.tsx.
src/lib/og/index.tsx: say which share-image style it uses.
public/looks/<id>/: the art and the placeholder pictures for the starter page. Add every file to public/looks/CREDITS.md with its source and licence. Only public domain, CC0 or art you made.
src/app/lab/: a component lab for the look, linked from src/app/lab/page.tsx (see src/app/lab/night/page.tsx).
Tests: a case for the starter in tests/unit/templates.test.ts, and any new schema behaviour in tests/unit/schema.test.ts. Run npm run schema afterwards.

To check it, run npm run dev and open:

/lab and the look’s component lab (/lab/<id>), in every state.
/lab/page/<id>?set=rich|sparse|photos|starter, optionally with &preset=<palette> and &layout=bento|list|canvas. Check every palette, on desktop and on a phone.
node scripts/page-shot.mjs <id> <set> [width] [preset] for a full-page screenshot in .scratch/shots/ (it needs the dev server running on port 3200: npx next dev -p 3200).

Design guidelines

Pastel and calm. No hard borders, no loud gradients, no badges or pills.
Motion is soft and fast; everything respects prefers-reduced-motion.
Check every change in a light and a dark theme, on desktop and on a phone.

Pull requests and releases

Keep pull requests small. Fill in the template, and add a screenshot for anything visual.
Add a line to CHANGELOG.md under “Unreleased” for user-facing changes.
CI runs typecheck, unit tests, build, end-to-end tests and CodeQL. All must pass.
Releases use one version number: package.json, server.json, plugin/**/plugin.json and .claude-plugin/marketplace.json change together, and CHANGELOG.md gets a dated heading.
Questions and ideas: GitHub Discussions. Docs: docs.posy.page.

​Setup

​Before you open a PR

​Where things live

​Adding a platform or a tile type

​Adding a look

​Design guidelines

​Pull requests and releases