How hayes/pothos works
Project type and purpose
• This is a monorepo for a TypeScript‐based GraphQL schema builder library (“Pothos”) and its plugin ecosystem.
• It contains:
– The core schema builder package (@pothos/core)
– A “converter” CLI tool
– ~30 first-class plugins (add-graphql, complexity, dataloader, prisma, relay, etc.)
– Deno-compatible mirrors of core/plugins in packages/deno
– Test utilities and example apps under examples/
– A NextJS‐based documentation website under website/
– Build/config scripts, CI workflows, and a Changesets‐powered release pipeline
File structure
• Top‐level config: pnpm-workspace.yaml, turbo.json, .github/workflows/*, changeset folder.
• packages/: each subfolder is an NPM package, sharing tsconfig.json, src/, optional tests/, esm/, and build outputs.
• examples/: dozens of sample GraphQL servers (Prisma, Fastify, Federation, NextJS, etc.) consuming the library.
• website/: NextJS app pulling in the packages (probably via a local workspace link) to generate docs.
• CI files orchestrate lint, build, test, docs deploy, and package publishing via Changesets and Turborepo pipeline.
Key README insights
• Pothos is purely a “schema‐builder” with zero runtime overhead beyond graphql-js.
• Plugin system: each plugin augments core’s builder API.
• No codegen is required; types flow directly via TypeScript inference.
• Wide plugin ecosystem for auth, complexity, directives, Prisma, Relay, mocks, subscriptions, tracing, etc.
a. Main components:
– Monorepo Root
• Workspace config, CI (GitHub Actions), Changesets, Turborepo
– Core Package (@pothos/core)
– Converter CLI (packages/converter)
– Plugin Packages
• E.g. plugin‐add‐graphql, plugin‐prisma, plugin‐dataloader, plugin‐complexity, plugin‐relay, …
• Deno mirrors under packages/deno group
– Test‐Utils (shared test server creation)
– Examples (example GraphQL servers showing library usage)
– Website (NextJS app for docs)
b. Relationships and data flows:
• Converter depends on core (to transform Pothos schemas into some target).
• Plugins also sometimes depend on each other (e.g., plugin-prisma-utils → plugin-prisma).
• Examples import core + relevant plugins to construct working GraphQL servers.
• Website imports core + plugin packages for live code samples and API docs.
• CI flow: changes in any package trigger Turborepo tasks (build, test), Changesets generate release plans, and GitHub Actions publishes updated packages to npm.
c. Architectural patterns/design principles:
• Monorepo + Turborepo for orchestrated builds and test caching
• Plugin‐based architecture: core provides an extensible schema builder; plugins register “hooks” into the builder API
• Workspace linking: local development runs cross‐package references without republishing
• Dual builds (ESM under esm/, types under .d.ts)
• Zero runtime overhead beyond the official GraphQL library
d. Relevant technologies:
• TypeScript, pnpm workspaces, Turborepo, GraphQL, graphql-yoga, NextJS, Deno support, Prisma, Fastify, NestJS, OpenTelemetry