Registry / devops / graphql-transform-federation

graphql-transform-federation

library2.2.0jsnpmunverified

A library that retrofits GraphQL federation support (Apollo Federation spec) onto an existing GraphQL schema that was not originally built for federation. v2.2.0 is current, with stable maintenance releases. Unlike apollo-server's built-in federation, this works with remote schemas, generated schemas, or any schema you can't rebuild from scratch. It adds @key, @external, @provides, @requires directives and __resolveReference resolvers. Requires graphql 14/15 and @apollo/federation 0.x peer dependencies. Ships TypeScript types.

devops

npm install graphql-transform-federation

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-TRANSFORM-

graphql-transform-federation

devopsjavascriptv2.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

transformSchemaFederation

✓ import { transformSchemaFederation } from 'graphql-transform-federation'

✗ import transformSchemaFederation from 'graphql-transform-federation'

The library exports a single named function, no default export.

Shows how to wrap a remote GraphQL schema with federation directives and a __resolveReference resolver for a Product type.

import { transformSchemaFederation } from 'graphql-transform-federation'; import { makeRemoteExecutableSchema } from 'graphql-tools'; import { HttpLink } from 'apollo-link-http'; import fetch from 'node-fetch'; const link = new HttpLink({ uri: 'http://existing-graphql/graphql', fetch }); const schema = makeRemoteExecutableSchema({ schema: await introspectSchema(link), link }); const federationSchema = transformSchemaFederation(schema, { Query: { extend: true }, Product: { extend: true, keyFields: ['id'], fields: { id: { external: true } }, resolveReference(reference) { return { id: reference.id }; }, }, });

Debug

Known issues

breakingThe package v2 uses the 'federationConfig' parameter structure changed from v1 - 'keyFields' replaced 'key' array, and 'fields' now uses FederationFieldConfig objects.

fix

Update config objects: use 'keyFields: ["id"]' instead of 'key: ["id"]', and 'fields: { id: { external: true } }' instead of 'fields: ["id"]'.

affects: 2.0.0 - 2.2.0

deprecatedThe '@apollo/federation' peer dependency is deprecated; federated schemas should use '@apollo/subgraph' in newer Apollo Server versions.

fix

If using Apollo Server 3+, use '@apollo/subgraph' (though this library may not fully support it yet – check compatibility).

affects: >=2.0.0

gotchaWhen using a remote schema, you must re-implement __resolveReference logic; it does NOT automatically delegate to the original schema's resolvers.

fix

Provide a resolveReference callback that calls delegateToSchema or fetches data from the original source.

affects: >=0.0.0

gotchaThe '@apollo/federation' version must match the graphql peer dependency version range; incompatible versions may cause type errors.

fix

Use @apollo/federation@0.x that is compatible with graphql 14/15. Check peerDependencies in package.json.

affects: >=2.0.0

gotchaThe transformSchemaFederation function does NOT validate the input config; invalid field names or missing resolvers may silently fail.

fix

Double-check all object type names, field names, and key fields exist in the original schema. Use TypeScript for compile-time checks.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Cannot find module '@apollo/federation'

@apollo/federation is a required peer dependency not installed.

fix

npm install @apollo/federation@0.x

GraphQLError: Type "Product" has no field "__resolveReference"

Object type is not federated – missing @key directive or resolveReference config.

fix

Add keyFields and resolveReference to the federationConfig for that type.

TypeError: transformSchemaFederation is not a function

Default import used instead of named import.

fix

Use import { transformSchemaFederation } from 'graphql-transform-federation';

Argument of type '{ key: string[]; fields: string[]; }' is not assignable to parameter of type 'FederationObjectConfig'

Config structure for v1 incompatible with v2.

fix

Use 'keyFields' (array of strings) and 'fields' (object mapping to FederationFieldConfig) instead.

Upgrade

Version history

2.2.0latest on npm

Audit

Dependencies

graphqlrequiredpeer dependency – core GraphQL types and schema manipulation

@apollo/federationrequiredpeer dependency – provides federation spec types (e.g. GraphQLReferenceResolver)

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/0xR/graphql-transform-federation ↗

packagegraphql-transform-federation ↗

homepagehttps://github.com/0xR/graphql-transform-federation#readme ↗