Playground

Most code blocks in these docs are live. Add the playground marker to a TypeScript fence and it gains an "Open in Playground" button that boots the code in an in-browser sandbox: an editor, the generated SDL, and a GraphiQL tab, with nothing to install. Attributes on the fence decide what opens and what runs.

Inline code

The playground marker on its own makes a fence runnable. Clicking loads the fence's exact code:

import SchemaBuilder from '@pothos/core';

const builder = new SchemaBuilder({});

const Character = builder.objectRef<{ id: string; name: string }>('Character');

Character.implement({
  fields: (t) => ({
    id: t.exposeID('id'),
    name: t.exposeString('name'),
  }),
});

builder.queryType({
  fields: (t) => ({
    frodo: t.field({
      type: Character,
      resolve: () => ({ id: 'frodo', name: 'Frodo Baggins' }),
    }),
  }),
});

export const schema = builder.toSchema();

Registered examples

Point example at a bundle ID to open a full, multi-file example instead of the single fence. The docs still show a focused slice; clicking loads every file in the bundle along with its default query:

import SchemaBuilder from '@pothos/core';

const builder = new SchemaBuilder({});

// Shown here in the docs; "Open in Playground" loads the full
// getting-started-first-schema-step-2 bundle — every file, plus its default query.
const Character = builder.objectRef<{ id: string; name: string }>('Character');

Character.implement({
  fields: (t) => ({
    id: t.exposeID('id'),
    name: t.exposeString('name'),
  }),
});

example values are kebab-case IDs that match a directory under website/playground-examples/. Every reference must resolve to a real bundle, or pnpm check-playground-refs fails the build. Keep the fence a faithful subset of the bundle's schema.ts so opening it is not jarring.

Pre-filled queries

Add query to open GraphiQL with an operation already typed in and focused:

import SchemaBuilder from '@pothos/core';

const builder = new SchemaBuilder({});

const Character = builder.objectRef<{ id: string; name: string }>('Character');

Character.implement({
  fields: (t) => ({
    id: t.exposeID('id'),
    name: t.exposeString('name'),
  }),
});

builder.queryType({
  fields: (t) => ({
    frodo: t.field({
      type: Character,
      resolve: () => ({ id: 'frodo', name: 'Frodo Baggins' }),
    }),
  }),
});

export const schema = builder.toSchema();

Example plus query

Combine the two to open a full bundle with a specific operation ready to run, handy for pointing readers at one capability of a larger schema:

// Opens the getting-started-first-schema-step-2 bundle with the query pre-filled.

The pre-filled query must be valid against the bundle it opens. Here { frodo { id name } } matches the frodo field that step 2 defines.

Multi-step examples

A bundle can ship a progression of steps, each a self-contained schema in its own step-N/ directory with its own default query. Reference a step with the -step-N suffix; the number resolves to that subdirectory:

// Opens step 2 of the getting-started-first-schema bundle.

Steps suit a page that builds a schema up one change at a time — see Installation, which opens step 1 and then step 2 as it walks through a first schema.

Switchable definition styles

To show one schema written several ways (object refs, classes, or builder types), give each fence a tab label. Consecutive fences that share the tab attribute merge into a single block with a style switcher, and "Open in Playground" opens whichever tab is selected:

```ts playground example="fundamentals-objects" tab="Object refs"
// primary style — the default (first) tab
```

```ts playground example="fundamentals-objects-variant-classes" tab="Classes"
// alternative style
```

```ts playground example="fundamentals-objects-variant-builder-types" tab="Builder types"
// alternative style
```

Each fence's example is the exact bundle it opens: the base ID for the default style, and <base>-variant-<slug> for the others. Author the alternatives as variant-<slug>/ subdirectories of the base bundle (see the playground examples README). A bundle uses steps or variants, never both.

The playground interface

Every playground opens with three tabs:

• Code: the TypeScript source, editable in place.
• Schema: the generated GraphQL SDL, which updates as you edit.
• GraphiQL: an interactive query editor wired to the schema.

Edit the code and the SDL and query results follow, so you can see exactly how a Pothos change reshapes the schema.