{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "paths": {
      "graphql-yoga": ["./src/vendor/graphql-yoga/src/index.ts"]
    }
  }
}

3. If you are using the source directly (not via npm), update your build tool (Vite, esbuild, webpack) to resolve the .js extensions in import paths to .ts source files, or set "allowImportingTsExtensions": true in tsconfig.json.

4. Ensure "moduleResolution" is "bundler" or "node16" — the source uses ESM .js extension imports throughout.

5. No environment variables are required by the core library. Optional: set NODE_ENV=production to suppress development-only GraphiQL and landing-page serving.

Public API

createYoga

function createYoga<
  TServerContext extends Record<string, any> = {},
  TUserContext extends Record<string, any> = {}
>(options: YogaServerOptions<TServerContext, TUserContext>): YogaServer<TServerContext, TUserContext>

The primary entry point. Returns a YogaServer instance with a handleRequest(request, serverContext) method compatible with Node.js http, Fetch API, and edge runtimes. Pass schema, plugins, context, graphiql, and maskedErrors options here.

createSchema

function createSchema<TContext>(options: {
  typeDefs: string | DocumentNode | Array<string | DocumentNode>;
  resolvers?: IResolvers<any, TContext> | Array<IResolvers<any, TContext>>;
}): GraphQLSchema

Convenience wrapper around @graphql-tools/schema makeExecutableSchema. Use it when you want to define your schema inline with SDL strings and resolver maps without importing @graphql-tools/schema directly.

createPubSub

function createPubSub<TTopicPayloadMap extends Record<string, unknown>>(
  options?: PubSubOptions
): PubSub<TTopicPayloadMap>

Creates a typed in-memory publish/subscribe bus for GraphQL subscriptions. Use pubsub.publish(topic, payload) in mutations and pubsub.subscribe(topic) in subscription resolvers. Exported from src/subscription.ts via src/index.ts.

maskError

function maskError(error: unknown, message: string, isDev?: boolean): GraphQLError

Strips internal error details before sending to clients. Wrap unexpected errors in resolvers or use Yoga's maskedErrors option to apply this automatically in production.

useReadinessCheck

function useReadinessCheck(options: {
  endpoint?: string;
  check?: () => PromiseOrValue<boolean | void>;
}): Plugin

Returns a Yoga plugin that exposes a readiness probe endpoint (default /ready). Pass it in the plugins array of createYoga. Useful for Kubernetes liveness/readiness probes.

Working examples

Scenario - Minimal Node.js HTTP server

A basic GraphQL API served over Node.js http with an inline schema and a single query resolver.

import { createServer } from 'node:http';
import { createYoga, createSchema } from './src/vendor/graphql-yoga/src/index.js';

const schema = createSchema({
  typeDefs: /* GraphQL */ `
    type Query {
      hello: String!
    }
  `,
  resolvers: {
    Query: {
      hello: () => 'Hello from Yoga!',
    },
  },
});

const yoga = createYoga({ schema });

createServer(yoga).listen(4000, () => {
  console.log('GraphQL server running at http://localhost:4000/graphql');
});

Scenario - Subscriptions with PubSub

A real-time subscription endpoint using the built-in in-memory PubSub bus.

import { createServer } from 'node:http';
import {
  createYoga,
  createSchema,
  createPubSub,
} from './src/vendor/graphql-yoga/src/index.js';

const pubsub = createPubSub<{ MESSAGE_ADDED: { messageAdded: string } }>();

const yoga = createYoga({
  schema: createSchema({
    typeDefs: /* GraphQL */ `
      type Query { _: Boolean }
      type Mutation { addMessage(text: String!): Boolean }
      type Subscription { messageAdded: String! }
    `,
    resolvers: {
      Mutation: {
        addMessage: (_: unknown, { text }: { text: string }) => {
          pubsub.publish('MESSAGE_ADDED', { messageAdded: text });
          return true;
        },
      },
      Subscription: {
        messageAdded: {
          subscribe: () => pubsub.subscribe('MESSAGE_ADDED'),
          resolve: (payload: { messageAdded: string }) => payload.messageAdded,
        },
      },
    },
  }),
});

createServer(yoga).listen(4000);

Scenario - Server context, readiness check, and masked errors

Attach per-request server context (e.g. the raw Node.js request), add a readiness probe, and mask internal errors in production.

import { createServer, IncomingMessage, ServerResponse } from 'node:http';
import {
  createYoga,
  createSchema,
  useReadinessCheck,
  maskError,
} from './src/vendor/graphql-yoga/src/index.js';

type ServerContext = { req: IncomingMessage; res: ServerResponse };

const yoga = createYoga<ServerContext>({
  schema: createSchema({
    typeDefs: `type Query { whoami: String! }`,
    resolvers: {
      Query: {
        whoami: (_: unknown, __: unknown, ctx) => {
          return ctx.req.headers['x-user'] ?? 'anonymous';
        },
      },
    },
  }),
  maskedErrors: {
    maskError: (err) => maskError(err, 'Unexpected server error', process.env.NODE_ENV !== 'production'),
  },
  plugins: [
    useReadinessCheck({
      endpoint: '/ready',
      check: async () => {
        // perform DB ping or similar
        return true;
      },
    }),
  ],
});

createServer((req, res) => yoga.handleRequest(req as any, { req, res })).listen(4000);

File walkthrough

• scripts/generate-graphiql.js - Fetches and inlines the GraphiQL bundle into src/graphiql.html at build time.
• scripts/inject-version.js - Rewrites the package version into generated files before publish.
• src/index.ts - Barrel that re-exports everything public from the library.
• src/server.ts - Contains createYoga, YogaServer, and the main request dispatch loop.
• src/schema.ts - Contains createSchema, a thin wrapper over makeExecutableSchema.
• src/subscription.ts - Contains createPubSub and supporting subscription async-iterator helpers.
• src/types.ts - All shared TypeScript interfaces: YogaServerOptions, YogaInitialContext, etc.
• src/error.ts - GraphQLError construction and HTTP-aware error helpers.
• src/process-request.ts - Core pipeline: parses request, runs Envelop, serializes result.
• src/graphiql.html - Static HTML shell for the embedded GraphiQL IDE.
• src/landing-page.html - Served on non-GraphQL GET requests in development mode.
• src/plugins/ - All built-in plugins: GraphiQL, health/readiness checks, request parsers, validators, result processors.
• src/plugins/request-parser/ - Handlers for GET, POST JSON, POST form-urlencoded, multipart, and raw GraphQL string bodies.
• src/plugins/request-validation/ - Guards for method enforcement, query param checks, batching limits, and GET-mutation prevention.
• src/plugins/result-processor/ - Serializers for regular JSON, SSE streaming, and multipart incremental delivery.
• src/utils/create-lru-cache.ts - LRU cache factory used internally for parse/validation caching.
• src/utils/mask-error.ts - Exports maskError for stripping sensitive error details.
• src/utils/is-response.ts - Type guard to detect Response objects from plugins.
• type-api-check.ts - Compile-time-only file verifying the public TypeScript API contracts.

Common pitfalls and fixes

• .js extension resolution fails with ts-node - Add "moduleResolution": "node16" or "bundler" in tsconfig.json and use ts-node --esm, or configure your loader to map .js imports to .ts sources.
• graphql peer dep version mismatch - Yoga requires a single graphql instance; if peerDependencies conflict, pin graphql in your root package.json and use npm dedupe.
• Subscriptions not working behind a proxy - SSE and WebSocket connections require the proxy to disable response buffering; set X-Accel-Buffering: no for nginx.
• GraphiQL served in production - Pass graphiql: false to createYoga to disable it; it defaults to enabled when NODE_ENV !== 'production' but the library does not auto-detect this in all runtimes.
• Multipart upload plugin conflicts - If you integrate graphql-upload separately, it will conflict with Yoga's built-in multipart parser; remove external upload middleware.
• ESM/CJS dual-mode confusion - When consuming source files directly (not the built npm package), ensure your bundler or tsconfig does not mix CommonJS output with ESM source imports; set "module": "ESNext" throughout.

Vibe-coding prompt template

I have dropped the GraphQL Yoga source library into `src/vendor/graphql-yoga/`.
The main barrel is at `src/vendor/graphql-yoga/src/index.ts`.
The reference doc is `USAGE.md` in the same directory.
The upstream package is `graphql-yoga` (monorepo package).

Please integrate GraphQL Yoga into my existing project step by step:

1. Read USAGE.md and the file excerpts to understand all available exports.
2. Install the required peer dependencies listed in USAGE.md.
3. Create a GraphQL schema using `createSchema` with my existing type definitions.
4. Create a Yoga server using `createYoga`, wiring in my server context type.
5. Mount the Yoga server on my existing Node.js HTTP / Express / Next.js handler.
6. Add `useReadinessCheck` for my Kubernetes probes at `/ready`.
7. Configure `maskedErrors` using `maskError` for production safety.
8. If I need subscriptions, set up `createPubSub` with typed topic payloads.
9. Ensure all imports use the real exported names from `src/vendor/graphql-yoga/src/index.ts`.
10. Do not invent any API methods — only use symbols documented in USAGE.md.

License and credit

GraphQL Yoga is published by The Guild under the MIT license. See source/LICENSE if present, or refer to the upstream repository at https://github.com/dotansimha/graphql-yoga. The upstream npm package is graphql-yoga.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完整安装指南与集成提示词将在购买后解锁。