Skip to content

v6: fix broken migration guide examples and transport docs#4432

Draft
trevor-scheer wants to merge 1 commit into
graphiql-6from
trevor/v6-docs-accuracy
Draft

v6: fix broken migration guide examples and transport docs#4432
trevor-scheer wants to merge 1 commit into
graphiql-6from
trevor/v6-docs-accuracy

Conversation

@trevor-scheer

Copy link
Copy Markdown
Contributor

Summary

A docs review cross-checked the migration guide and package READMEs against the actual graphiql-6 source and found several that describe APIs that no longer exist. The migration guide's useDocExplorer/useHistory "after" examples pass a selector argument and destructure fields (.navStack, .items) that don't exist — both hooks take zero arguments and return the value directly, so copying the examples as written is a compile error. The graphiql and graphiql-react READMEs describe transport as "a function," which is the old Fetcher shape; it's an object with a send() method. The createTransport link in graphiql/README.md pointed at createFetcher.ts, and neither README mentioned that fetcher still works. The "Editor Theme" section documented a CodeMirror API that hasn't existed since the Monaco rewrite. The toolkit's own README never mentioned createTransport, its biggest new export. create-fetcher.md's deprecation banner linked to a create-transport.md file that doesn't exist, and (found while fixing that line) the migration-guide link right next to it was also pointing one directory too shallow.

Also added the ExecuteButton removal to the migration guide's breaking-changes notes, reworded the .browserslistrc line (the file still exists, only its contents changed to defaults), and added the v6 migration guide to graphiql/README.md's getting-started list, which already linked to it later in the doc but didn't list it up top.

Test plan

  • Copy the useDocExplorer and useHistory "after" examples from the migration guide into a scratch .tsx file inside the repo and confirm they compile with no excess-argument or missing-field errors.
  • In graphiql/README.md, click the createTransport link and confirm it lands on createTransport.ts, not createFetcher.ts.
  • In packages/graphiql-toolkit/docs/create-fetcher.md, click both links in the deprecation banner and confirm each resolves to a real file.
  • In packages/graphiql-toolkit/README.md, click the new createTransport link and confirm it resolves.
  • Read the rewritten "Editor Theme" section in graphiql/README.md and confirm the editorTheme prop example matches what <GraphiQL> actually accepts (a { dark, light } pair of Monaco theme names, not a CodeMirror theme string).
  • Confirm packages/graphiql-toolkit/src/create-transport/README.md does not appear in this PR's diff.

Refs: #4219

The useDocExplorer/useHistory "after" examples in the v6 migration
guide passed a selector argument and destructured fields that don't
exist on either hook - both take zero arguments and return the value
directly, so copying the examples was a straight compile error.

The graphiql and graphiql-react READMEs still described transport as
"a function," which is the old Fetcher shape; it's an object with a
send() method. Fixed that, pointed the createTransport link at the
right file (it was linking to createFetcher.ts), and added a note that
fetcher still works since neither README mentioned it. Rewrote the
Editor Theme section in graphiql/README.md, which was describing a
CodeMirror API that hasn't existed since the Monaco move, and while in
there fixed another dead link to the migration guide in
create-fetcher.md's deprecation banner. The toolkit README got a
createTransport entry alongside createFetcher, and the v6 migration
guide is now listed in graphiql/README.md's getting-started section.

Also added the ExecuteButton removal note to the migration guide's
breaking-changes list and reworded the browserslistrc line (the file
still exists, only its contents changed).
@changeset-bot

changeset-bot Bot commented Jul 15, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: fdc2ac3

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

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.

1 participant