vault backup: 2026-05-15 15:47:15

wiki/_master-index.md

@@ -35,7 +35,7 @@ This 3-hop pattern works for hundreds of articles without vector search.
 | [[wiki/reports/_index\|reports/]] | Weekly and monthly summaries — generate: `uv run python scripts/report-generator.py --weekly` | 1 |
 | [[wiki/infrastructure/_index\|infrastructure/]] | Server inventory: all 10 SSH hosts — optical, optical-dev, optical-prod, baic, librechat, modocmms, box-cli, aimpress, pve | 12 |
 | [[wiki/testing/_index\|testing/]] | Web app testing: functional, performance, security, UI types; TDD/BDD/Agile methodologies; Selenium/Cypress/Playwright/JMeter/OWASP ZAP tools | 1 |
-| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization | 88 |
+| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization | 89 |
 
 | [[wiki/shared-patterns/_index\|shared-patterns/]] | Oliver Agency standard library patterns: httpx, structlog, pydantic-settings, alembic — reuse before writing from scratch | 4 |
 | [[wiki/mistakes/_index\|mistakes/]] | Anti-patterns extracted from sessions — per-stack running lists (fastapi, react, docker, postgres, general) — injected at session start | 5 |

wiki/payloadcms/_index.md

@@ -90,3 +90,4 @@
 | [[wiki/payloadcms/concepts-overview\|Core Concepts]] | Config, Collections, Globals, Fields, Hooks, Auth, Access Control, Admin Panel; Local/REST/GraphQL APIs; package structure | raw/getting-started__concepts.md | 2026-05-15 |
 | [[wiki/payloadcms/installation\|Installation]] | Requirements (Node 24+, Next.js 16.2.6+), create-payload-app quickstart, manual install steps, withPayload ESM config, tsconfig path alias | raw/getting-started__installation.md | 2026-05-15 |
 | [[wiki/payloadcms/graphql-extending\|GraphQL — Custom Queries and Mutations]] | Add custom GraphQL ops via `graphQL.queries`/`graphQL.mutations` in buildConfig; resolver signature, `depth: 0` gotcha, `buildPaginatedListType`, collection graphQL types | raw/graphql__extending.md | 2026-05-15 |
+| [[wiki/payloadcms/graphql-schema\|GraphQL — Schema Generation]] | `payload-graphql generate:schema` CLI, PAYLOAD_CONFIG_PATH for non-root configs, `interfaceName` for reusable top-level GraphQL types | raw/graphql__graphql-schema.md | 2026-05-15 |

wiki/payloadcms/graphql-schema.md

@@ -0,0 +1,88 @@
+---
+title: "GraphQL — Schema Generation"
+aliases: [graphql-schema, generate-graphql-schema, payload-graphql]
+tags: [payloadcms, graphql, codegen, typescript]
+sources: [raw/graphql__graphql-schema.md]
+created: 2026-05-15
+updated: 2026-05-15
+---
+
+## Overview
+
+Payload auto-generates a GraphQL schema from your Collections and Globals. The `@payloadcms/graphql` package exposes a CLI command to dump the full schema to a file.
+
+## Schema Generation
+
+Install as a dev dependency:
+
+```bash
+pnpm add @payloadcms/graphql -D
+```
+
+Run the generator:
+
+```bash
+pnpm payload-graphql generate:schema
+```
+
+- Default output: `./schema.graphql` (current working directory)
+- If `graphQL.schemaOutputFile` is set in `buildConfig`, output goes there (e.g. `./graphql/schema.graphql`)
+
+## Config Path Detection
+
+Payload auto-detects your config, but fails if it lives in a non-standard location (e.g. `src/`). Fix with an npm script using `PAYLOAD_CONFIG_PATH`:
+
+```json
+// package.json
+{
+  "scripts": {
+    "generate:graphQLSchema": "cross-env PAYLOAD_CONFIG_PATH=src/payload.config.ts payload-graphql generate:schema"
+  }
+}
+```
+
+## Custom Field Interfaces (`interfaceName`)
+
+For `array`, `block`, `group`, and named `tab` fields, set `interfaceName` to produce a **top-level reusable GraphQL type** instead of an inline type:
+
+```ts
+{
+  type: 'group',
+  name: 'meta',
+  interfaceName: 'SharedMeta',
+  fields: [
+    { name: 'title', type: 'text' },
+    { name: 'description', type: 'text' },
+  ],
+}
+```
+
+Generated schema:
+
+```graphql
+# Reusable top-level type
+type SharedMeta {
+  title: String
+  description: String
+}
+
+# Referenced in the collection
+type Collection1 {
+  meta: SharedMeta
+}
+```
+
+This mirrors how `interfaceName` works for [[wiki/payloadcms/typescript|TypeScript type generation]] — same field config option, two outputs.
+
+## Key Takeaways
+
+- `pnpm payload-graphql generate:schema` dumps the full schema to `schema.graphql`
+- Set `PAYLOAD_CONFIG_PATH` env var when config is not at the project root
+- `interfaceName` on group/array/block/tab fields creates reusable top-level GraphQL types (avoids inline duplication)
+- Schema generation is a dev-time step — add it to CI alongside `generate:types` for drift detection
+- Related: [[wiki/payloadcms/graphql-extending|GraphQL — Custom Queries and Mutations]] for adding custom ops on top of the generated schema
+
+## Sources
+
+- `raw/graphql__graphql-schema.md`
+- https://payloadcms.com/docs/graphql/graphql-schema