frontpage.fyi / frontpage
AT-based link agregator. Mirror of https://github.com/likeandscribe/frontpage
fork atom

Add Copilot onboarding guide for frontpage monorepo (#301)

* Initial plan

* docs: add copilot onboarding instructions

Co-authored-by: timothyis <1695613+timothyis@users.noreply.github.com>

* docs: clarify install troubleshooting note

Co-authored-by: timothyis <1695613+timothyis@users.noreply.github.com>

* docs: note stable next 16

Co-authored-by: timothyis <1695613+timothyis@users.noreply.github.com>

* Fix lexicons path

* Update .github/copilot-instructions.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Add copilot instructions to prettier ignore

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: timothyis <1695613+timothyis@users.noreply.github.com>
Co-authored-by: Tom Sherman <the.tomsherman@gmail.com>
Co-authored-by: Tom Sherman <tom@sherman.is>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

authored by

Copilot
timothyis
Copilot
copilot-swe-agent[bot]
Tom Sherman
Tom Sherman and committed by
GitHub 8b5135d6 553b4439

+74
unified split
+71
.github/copilot-instructions.md
··· 1 + # Copilot onboarding guide 2 + 3 + Trust these notes before searching; only explore if something here is missing or incorrect. 4 + 5 + ## What this repo is 6 + - **Frontpage**: a federated link aggregator on the ATProto/Bluesky network. Main web app lives in `packages/frontpage` (Next.js, Turbopack, Tailwind, Drizzle ORM). 7 + - **Other apps/libs**: `packages/atproto-browser` (Next.js browser for ATProto), `packages/unravel` (Next.js marketing site), `packages/frontpage-atproto-client` (TypeScript client + generated lexicons), `packages/frontpage-oauth` & `packages/frontpage-oauth-preview-client` (OAuth helpers/demo). 8 + - **Rust services** (Cargo workspace in `packages-rs/*`): drainpipe + related tooling for ingesting the ATProto firehose. 9 + - **Lexicons**: ATProto lexicon definitions under `lexicons/fyi/frontpage`. 10 + 11 + ## Tooling & runtimes 12 + - Node **v22.18.0** (`.nvmrc`); pnpm **10.12.0** (declared in root `package.json`); turbo **2.5.0**. 13 + - TypeScript 5.9, Next 16 (Turbopack), React 19, Vitest, ESLint 9, Prettier 3. 14 + - Drizzle ORM migrations in `packages/frontpage/drizzle` with `drizzle.config.ts`. 15 + - Go tool `glot` is used only in lexicon CI; not needed for most tasks unless touching `lexicons/`. 16 + - Rust stable via Cargo for `packages-rs/*`. 17 + 18 + ## Repository layout (high-value paths) 19 + - Root: `package.json`, `pnpm-workspace.yaml`, `turbo.json`, `.nvmrc`, `pnpm-lock.yaml`, `Cargo.toml`, `README.md`, `CONTRIBUTING.md`, workflows in `.github/workflows/`. 20 + - Frontend app: `packages/frontpage/` (Next config `next.config.mjs`, lint config `eslint.config.mjs`, TS config `tsconfig.json`, Tailwind/postcss configs, Vercel config, Drizzle migrations/config, `app/` routes). 21 + - Supporting apps/libs: `packages/atproto-browser/`, `packages/unravel/`, `packages/frontpage-atproto-client/`, `packages/frontpage-oauth/`, `packages/frontpage-oauth-preview-client/`, `packages/typescript-config/`, `packages/eslint-config/`. 22 + - Rust services: `packages-rs/drainpipe`, `packages-rs/drainpipe-cli`, `packages-rs/drainpipe-store`, `packages-rs/jetstream`. 23 + - Local dev infra: `packages/frontpage/local-infra` (docker-compose, CA certs, Cloudflare tunnel notes, test-account script). 24 + 25 + ## CI expectations 26 + - PR workflow runs (see `.github/workflows/pr.yml`): 27 + - `pnpm exec prettier --check .` 28 + - `pnpm exec turbo run --affected lint` 29 + - `pnpm exec turbo run --affected test` 30 + - `pnpm exec turbo run --affected type-check` 31 + - Lexicon changes (`lexicons/**`) trigger Go-based `glot lint` and `glot compat`. 32 + - Label sync on PRs; `sync-tangled` push job mirrors `main` to tangled.sh (uses secret). 33 + 34 + ## Setup / bootstrap 35 + 1. Ensure Node 22.18 available (`nvm use`). 36 + 2. Enable Corepack so pnpm 10.12.0 is provisioned: `corepack enable`. 37 + 3. Install JS deps from repo root: `pnpm install`. 38 + - If you see `ENOTFOUND npm.jsr.io` while fetching `@jsr/lpm__core@0.2.9` (pulled by `packages/atproto-browser`), it is a network/DNS issue: confirm egress/DNS can reach `npm.jsr.io` or route through a proxy. CI typically resolves this normally. 39 + 40 + ## Common commands (run from repo root unless noted) 41 + - **Format check**: `pnpm exec prettier --check .` 42 + - **Lint**: `pnpm exec turbo run lint` (or `--filter <package>` to narrow). Frontpage package also supports `pnpm --filter frontpage run lint`. 43 + - **Tests**: `pnpm exec turbo run test` (Vitest). Per-package: `pnpm --filter frontpage run test`, etc. 44 + - **Type-check**: `pnpm exec turbo run type-check` or `pnpm --filter frontpage run type-check`. 45 + - **Build**: 46 + - Frontpage app: `pnpm --filter frontpage run build` (Turbopack; uses `NODE_OPTIONS=--use-openssl-ca` in script). 47 + - atproto-browser/unravel: `pnpm --filter <pkg> run build`. 48 + - Frontpage ATProto client: `pnpm --filter @repo/frontpage-atproto-client run build` (tsc). 49 + - **Dev servers**: 50 + - Frontpage app: `pnpm --filter frontpage exec turbo dev` (or `pnpm --filter frontpage run dev`). For production DB access, team uses `dev-1pw` which relies on 1Password CLI and `.env.1pw`. 51 + - atproto-browser/unravel: `pnpm --filter <pkg> run dev`. 52 + - **DB / Drizzle (frontpage)**: run inside `packages/frontpage`: `pnpm db:generate`, `pnpm db:migrate`, `pnpm db:push`, `pnpm db:studio`, `pnpm db:pull`. Scripts set `NODE_OPTIONS=--use-openssl-ca`. 53 + - **Lexicon tooling**: From root, install Go `glot` (see workflow) then `glot lint lexicons/fyi/frontpage` / `glot compat lexicons/fyi/frontpage` when touching lexicons. 54 + - **Rust services**: Standard Cargo; e.g., `cargo build -p drainpipe` from repo root. Docker build example in `packages-rs/drainpipe/README.md`. 55 + 56 + ## Local infra (frontpage app) 57 + - Follow `packages/frontpage/local-infra/README.md`: 58 + - `docker-compose up` to run PLC, PDS, Jetstream, Drainpipe, Turso, Caddy, cloudflared tunnel. 59 + - Install Unravel CA (`frontpage-local-infra_caddy_data/pki/authorities/unravel/root.crt`) and set `NODE_OPTIONS=--use-openssl-ca` for Node apps (frontpage scripts already set this). 60 + - Generate `.env.local` via `pnpm --filter=frontpage run generate-local-env`, run `pnpm db:migrate`, start app with `pnpm --filter frontpage exec turbo dev` (or `pnpm --filter frontpage run dev`) from the repo root, grab cloudflared tunnel URL for access. 61 + - Troubleshooting steps for docker platforms, SSL renewal, Cloudflare 502, Windows WSL reset are in the README. 62 + 63 + ## Notes / tips 64 + - The repo is a pnpm + turbo monorepo; tasks cascade via `turbo.json` (`dependsOn: ["^build"]` etc.). 65 + - Config locations: lint configs per package (`eslint.config.mjs`), TS configs per package, Tailwind/PostCSS in frontend apps, Drizzle config in `packages/frontpage/drizzle.config.ts`, Vercel config `packages/frontpage/vercel.json`. 66 + - If you run Node commands manually (not through package scripts) while using the local CA, export `NODE_OPTIONS=--use-openssl-ca`. 67 + - Lexicon-related changes require Go toolchain; other changes do not. 68 + - If package installs fail with `npm.jsr.io` DNS errors, fix network access first; lint/test/build commands depend on a complete install. 69 + 70 + ## File listing (root, high level) 71 + `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, `README.md`, `SECURITY.md`, `LICENSE`, `.nvmrc`, `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `turbo.json`, `Cargo.toml`, `lexicons/`, `packages/`, `packages-rs/`, `.github/workflows/`.
+3
.prettierignore
··· 2 2 pnpm-workspace.yaml 3 3 packages/frontpage/drizzle/meta 4 4 **/dist/** 5 + 6 + # Ignoring llm instructions to preserve any formatting inserted for the benefit of the model 7 + .github/copilot-instructions.md