All jobs

Upgrade graphql-js in a GraphQL API

Yes. The agent moves graphql-js up one major at a time with graphql-relay beside it, fixes each removed API, proves the schema is unchanged and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

How far a GraphQL server can upgrade is decided by its neighbours, so the agent reads the peer ranges before it reads a changelog. In a server like graphql/swapi-graphql, package.json pins graphql at exactly 14.5.8, graphql-relay at 0.6.0 and dataloader at 1.4.0, with graphql-http at ^1.22.4. package-lock.json records what each allows: the installed graphql-relay accepts no graphql newer than major 14, and the installed graphql-http declares >=0.11 <=16. So graphql and graphql-relay have to move together, and the highest major this lock can reach without replacing the HTTP layer is 16. The agent asks the registry for the newest release of each major with npm view graphql dist-tags and for the peer ranges of newer graphql-relay and graphql-http releases, and states the target and the reason before it installs anything.

It records a baseline, which in this repository takes more than npm test. npm ci triggers postinstall, which runs npm run download && npm run build: the first fetches every resource from swapi.tech into cache/data.json, a file git ignores and every test imports, and the second compiles src to lib with Babel. npm test is then eslint, flow check and jest in sequence. The agent also runs npm run print-schema and compares the output with the committed schema.graphql, so it knows whether the two agreed before it changed anything.

It goes up one major at a time and runs everything at each step, because the release before a removal is the one that warns about it. Two places in this codebase call APIs that a later major takes away. The test helper src/schema/__tests__/swapi.js and schema.spec.js both call graphql(swapiSchema, query) with positional arguments, and graphql-js 16 accepts a single object with schema and source. In src/schema/relayNode.js the type resolver passed to nodeDefinitions returns a GraphQLObjectType object picked by swapiTypeToGraphQLType, and graphql-js 16 requires a resolver to return the type's name. The agent changes each to the documented form, keeps the source files' @flow strict annotations valid, and checks that handler/graphql.mjs, which imports the built ../lib/schema and hands schema.default to createHandler, still loads.

The proof that clients see no difference is the schema itself. After the upgrade the agent prints the schema again and compares it with the baseline in two ways. As text, where differences in how a newer printSchema formats descriptions are expected and are set apart from the rest. And as types: it builds both versions with buildSchema and runs findBreakingChanges and findDangerousChanges from graphql-js over the pair, which must return nothing. It regenerates schema.graphql with npm run store-schema only if the printed form changed, and says so. It then runs each query under doc/example_queries against the upgraded schema and reruns npm test. dataloader stays where it is unless the prompt asks for it, since a single loader shared at module scope in src/schema/apiHelper.js deserves its own review.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Upgrade graphql-js in this GraphQL server to the newest major its other dependencies allow. Read package.json, package-lock.json, .nvmrc, .babelrc, jest.config.js, .flowconfig, the scripts directory, the handler directory and everything under src first. List the declared and locked versions of graphql and every package that has it as a peer, with each peer range. Use npm view to read graphql's dist-tags and the peer ranges of newer releases of those packages, then state the target major and which package limits it. Record a baseline: npm ci (note what postinstall does and whether it needed the network), npm test, npm run print-schema saved to a file, a comparison of that file with the committed schema.graphql, and each query under doc/example_queries executed against the schema. Then move graphql up one major at a time, moving graphql-relay to a release whose peer range allows it at the same step. At each step read that major's release notes, run npm test, and fix what broke with the documented replacement: single-object arguments to graphql() and execute(), type resolvers that return a type name, and renamed or removed utilities. Do not change resolver behaviour, do not upgrade dataloader, Babel, Jest, ESLint or Flow unless a step cannot pass without it, and say so if that happens. After the last step, print the schema again and compare it with the baseline as text and with findBreakingChanges and findDangerousChanges; both must report nothing. Regenerate schema.graphql only if its printed form changed. Rerun the example queries and confirm the handler module still loads the built schema. Open a pull request with the version table, one section per major listing what changed and why, the schema comparison, and the command output before and after.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

A pull request that changes package.json and package-lock.json, the call sites that used a removed API, and schema.graphql only if its printed form moved. The description starts with a version table for graphql and each package that peers on it, and one sentence naming the package that set the ceiling, with its peer range quoted from the lock or the registry.

It has one section per major crossed. Each lists what that release removed or changed that this codebase used, the file and line that was edited, and the result of npm test at that step. The schema comparison follows: the text diff with formatting-only changes labelled, and the output of the breaking-change and dangerous-change checks, which is empty when the upgrade is clean. The example queries are listed with their result before and after.

A reviewer checks the comparison first, because it is the statement that no client query changes meaning. They read each edited call site, of which there should be few. They also note what the run could not cover: the deployed function is built and served by the hosting platform, so the first request against a deploy preview is still worth making by hand. If swapi.tech could not be reached during install, the description says the tests ran against no data and the run stops there.

Run it on every quarter

A library this central does not need weekly attention, but it should not fall several majors behind either. An automation in the Project that holds the repository, with this prompt and a schedule trigger whose cron fires on the first day of each quarter in your timezone, starts one run. When graphql is already on the newest major its peers allow, the agent reports which package is holding it there and opens no pull request.

An organisation with many GraphQL services sends the same body from a script: GET /o/{org}/github lists the repositories, and one POST /o/{org}/sessions per repository starts its run, each with a request_id that is a UUID v5 of the repository's full name and the quarter, so a rerun of the script starts nothing twice. Runs past the key's concurrency limit are created queued and start as slots free.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

Why run it on Rush?

A major upgrade done one step at a time means installing, building and testing several times over, reading release notes in between, and diffing a schema at the end. It is hours of attention on a laptop for a change whose diff is a few lines. A sandbox does the waiting, starts from a clean install each run, and keeps every command and its output, so the step where a test first failed is on record with the error.

For an API, the evidence matters more than the version number. The pull request carries the schema comparison and the example queries' results, and the transcript at GET /o/{org}/sessions/{id}/messages shows the commands that produced them. A reviewer can decide to merge on what was proven without repeating the work.

Frequently asked questions

Why go one major at a time?

Each graphql-js major removes APIs the previous one deprecated, and the intermediate release is where the deprecation is still reported. Stopping at each step and running the tests ties every failure to one release's notes, which keeps the fixes small and the pull request readable.

Will the upgrade change my schema?

It should not, and the run checks that. The agent prints the schema before and after and compares them with graphql-js's own breaking-change and dangerous-change checks. Formatting differences in the printed SDL are reported separately from type differences, and any type difference stops the run with the details.

What if a dependency does not support the new major?

Then that dependency sets the target. The agent reads each package's peer range, looks for a newer release that widens it, and stops at the highest major every package accepts. The pull request names the package and its range so the team can decide whether to replace it.

Does it upgrade Babel, Jest or Flow at the same time?

No, unless a step cannot pass without it, in which case the description says which tool and why. Old build tooling is a separate upgrade with its own risks, and mixing it in would make a failed test impossible to attribute.

More GraphQL jobs

More jobs like this: Upgrade dependencies weekly

Keep reading