Skip to content

docs: replace Pothos stop-migration rules with complete GQLoom paths (en, zh) - #433

Merged
xcfox merged 1 commit into
mainfrom
cursor/pothos-complete-migration-guide-72b4
Nov 18, 2026
Merged

xcfox merged 1 commit into
mainfrom
cursor/pothos-complete-migration-guide-72b4

Conversation

@xcfox

@xcfox xcfox commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

Summary

Updates both the English (website/docs/migrations/from-pothos.md) and Chinese (website/zh/docs/migrations/from-pothos.md) Pothos → GQLoom migration guides to cover a complete migration with zero leftover Pothos modules:

  • Removed all "stop and keep Pothos" guidance: deleted the mapping-table "Stop; keep Pothos for that module" row, replaced rule GraphQL validates return type too early #15 (and updated rules Add GQLoom Icon #1, Only select querying fields #13, feat(resolver): implement ChainFactory for resolver composition #14, docs(website): migrate to fumadocs #16), and removed the When to migrate, when to stop / 何时迁移与何时停止 section.
  • Added complete GQLoom migration paths:
    • Relay: silk(new GraphQLInterfaceType(...)) for Node (preserving node / nodes interface return types without duplicate type errors), Zod silks for PageInfo, *Edge, and *Connection matching before.graphql nullability and global ID/cursor encoding.
    • Errors: Result union types (z.discriminatedUnion / z.union + Error interface silk) when before.graphql has a union, or GraphQLError with extensions when it does not, with explicit documentation of the SDL/response contract change and client adaptation when dropping error unions.
    • Sub-graphs: Separate weave() call per audience passing only that audience's resolvers and field-hiding resolvers (field.hidden scoped to a single weave()).
    • Smart Subscriptions: Standard subscription() operations + pubsub (createPubSub) with explicit pubSub.publish(...) calls in mutations, plus documentation of client/behavior adaptation when moving live queries or nested invalidations to Subscription.
    • Variants & generated filter/order inputs: Separate silks named with .meta({ title }) (and Zod v4 getter syntax / inner-z.lazy .meta({ title }) for recursive filters) preserving original SDL type names so clients see no change.
  • Updated Gotchas, Verification, and Cleanup: documented the silk(new GraphQLInterfaceType(...)) fix for interface-typed fields, inner .meta({ title }) placement on z.lazy(...), single-query include/with fallback for hot ORM paths, and expanded the final Pothos uninstall list.

Verification

  • Verified pnpm run check:lint (biome lint .) passes across 387 files.
  • Verified pnpm run check:type passes across all workspace packages and website checks.
  • Verified NODE_OPTIONS="--max_old_space_size=8192" pnpm --filter website build (including VitePress Twoslash compilation of every ts twoslash snippet in both en and zh docs) succeeds cleanly.
  • Verified runtime SDL generation (validateSchema, printSchema) and GraphQL execution for Relay (Node, PageInfo, *Edge, *Connection), Errors unions, Sub-graphs, Smart Subscriptions (createPubSub), and Drizzle variants + recursive filter/order inputs.
Open in Web Open in Cursor 

@xcfox
xcfox merged commit 17705e1 into main Nov 18, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants