graphql-s2s

0.22.0 verified Fri May 01 auth: no javascript

GraphQL S2S (Schema-to-Schema) is a transpiler that extends standard GraphQL SDL with type inheritance, generic types, metadata decoration, and query deconstruction/transformation/rebuilding. Version 0.22.0 is the latest stable release. It allows developers to define reusable schema patterns before transpiling to standard GraphQL syntax for graphql-js and Apollo Server. Key differentiators: supports multiple inheritance, generic type parameters (like Paged<T>), schema-level metadata annotations, and programmatic query manipulation. Unlike graphql-modules or type-graphql, graphql-s2s works purely at the SDL string level without requiring class definitions or decorators.

Common errors

error TypeError: Cannot destructure property 'transpileSchema' of 'require(...).graphqls2s' as it is undefined ↓

cause Using old import pattern with newer version that exports directly.

fix

Use import { transpileSchema } from 'graphql-s2s' (ESM) or const { transpileSchema } = require('graphql-s2s').graphqls2s only for versions <0.16.0; for >=0.16.0 use const { graphqls2s } = require('graphql-s2s'); const { transpileSchema } = graphqls2s.

error Error: Cannot find module 'graphql-s2s' ↓

cause Package not installed or incorrect path.

fix

Run 'npm install graphql-s2s' and ensure node_modules contains it.

error GraphQLError: Syntax Error: Expected Name, found <EOF> ↓

cause Generic type used without instantiation (e.g., using Paged in schema without angle brackets).

fix

Instantiate the generic: type Paged<T> { data: [T] } then type Query { items: Paged<Item> }.

error TypeError: graphqls2s is not a function ↓

cause Calling require('graphql-s2s') directly as a function in older versions.

fix

Use require('graphql-s2s').graphqls2s.transpileSchema(...) or import the named export.

Warnings

breaking In v0.16.0, the package switched from default export to named exports. require('graphql-s2s') no longer returns a function. ↓

fix Use destructuring: const { transpileSchema } = require('graphql-s2s').graphqls2s (old) or import { transpileSchema } from 'graphql-s2s' (new).

deprecated The .graphqls2s property for CommonJS require access is deprecated and may be removed in future versions. ↓

fix Use named ESM imports or await import('graphql-s2s').

gotcha Inheritance does not merge fields from parent types automatically; you must manually add fields to the child. The 'inherits' keyword only copies fields at transpile time, not during schema execution. ↓

fix Always declare all fields in the child type, even if inherited.

gotcha Generic types like Paged<T> must be instantiated with a concrete type; generics without instantiation will cause parse errors. ↓

fix Always use Paged<Question> not just Paged.

gotcha The transpiled schema may contain duplicate type definitions if multiple inheritance chains have overlapping fields; transpileSchema does not deduplicate. ↓

fix Manually deduplicate or use interface merging patterns.

Install

npm install graphql-s2s

yarn add graphql-s2s

pnpm add graphql-s2s

Imports

transpileSchema

wrong

const transpileSchema = require('graphql-s2s').graphqls2s.transpileSchema

correct

import { transpileSchema } from 'graphql-s2s'

ESM named export since v0.18.0; CommonJS users need to destructure from .graphqls2s.

graphqls2s
wrong
```
const graphqls2s = require('graphql-s2s')
```
correct
```
import { graphqls2s } from 'graphql-s2s'
```
Default export is the graphqls2s object (CommonJS compatibility); ESM prefers named exports.
deconstructQuery
```
import { deconstructQuery } from 'graphql-s2s'
```
For query AST manipulation; available since v0.12.0.

Quickstart

Shows transpilation of an enriched schema with inheritance to standard GraphQL.

import { transpileSchema } from 'graphql-s2s';
import { makeExecutableSchema } from '@graphql-tools/schema';

const enrichedSchema = `
type Node {
  id: ID!
}
type Person inherits Node {
  firstname: String
  lastname: String
}
type Query {
  people: [Person]
}
`;

const schema = makeExecutableSchema({
  typeDefs: [transpileSchema(enrichedSchema)],
  resolvers: {
    Query: {
      people: () => [{ id: '1', firstname: 'John', lastname: 'Doe' }]
    }
  }
});

// schema is now ready for graphql execution