@pothos/core 4.x

Complete instructions

Pothos Core 4

Historical validation of the earlier revision: Verified against @pothos/core@4.13.1 on 2026-09-07. 7 of 7 examples executed. That revision checked shapes and imports, not full consumer type checking or server execution. Current fixture evidence is recorded separately.

Inspect the installed versions, builder generics, plugins and context first. Reuse the existing builder. Pothos builds the schema; GraphQL.js executes operations and a server such as Yoga handles HTTP.

Add a typed field

Import default SchemaBuilder and specify context in its type map. Required arguments and non-null output are independent choices; write both when required by the contract.

import assert from "node:assert/strict";
import SchemaBuilder from "@pothos/core";
import { graphql, validateSchema } from "graphql";

type Context = { requestId: string };
const builder = new SchemaBuilder<{ Context: Context }>({});
builder.queryType({
  fields: (t) => ({
    greeting: t.string({
      nullable: false,
      args: { name: t.arg.string({ required: true }) },
      resolve: (_parent, { name }, context) =>
        `${context.requestId}: Hello ${name}`,
    }),
  }),
});
const schema = builder.toSchema();
assert.deepEqual(validateSchema(schema), []);
const result = await graphql({
  schema,
  source: "query Greeting($name: String!) { greeting(name: $name) }",
  variableValues: { name: "Ada" },
  contextValue: { requestId: "first" },
});
assert.equal(result.errors, undefined);
assert.equal(result.data?.greeting, "first: Hello Ada");

A numeric t.string resolver must fail TypeScript checking. Do not hide it with any or casts. Incoming JSON still needs runtime GraphQL validation.

Preserve schema defaults

• v4 fields are nullable by default. Use nullable: false for required outputs and inspect project defaults before changing them globally.
• A deliberate v3 migration can use the Defaults: "v3" type map with defaults: "v3"; do not change defaults incidentally while adding a field.
• v4 ID input is a string; output supports string, number or bigint. Review scalar overrides explicitly.
• Build shared shapes with builder.objectRef<Shape>("Name"). Generic helpers need the declared schema types; unknown does not satisfy SchemaTypes.

Require validateSchema(builder.toSchema()) to return no errors before serving. Shape assertions alone miss reserved names and other GraphQL invariants.

Serve with request context

Pass the schema to createYoga({ schema, context }). Create initContextCache() inside each context factory when caching is used, then merge request identity/dependencies. A shared cache can share request-specific data.

Plugin registration is a side effect; import registration before configuring its name. Follow installed plugin type augmentation requirements. Use import type for types such as SchemaTypes with verbatimModuleSyntax.

The fixture targets Pothos 4.13.1, GraphQL 16.13.1 and Yoga 5.22.0. It compiles a typed consumer and deliberately invalid resolver, validates the schema, executes operations and checks request isolation. It does not validate every scalar, plugin, subscription or adapter.

Primary sources

• Schema builder
• Context
• Upstream