NestJS GraphQL Schema-First

Defining Schema SDL

Write operations and types in GraphQL SDL, point GraphQLModule at those files with typePaths, and optionally generate TS types with definitions generators.

# schema.graphql
type Cat {
  id: ID!
  name: String!
  breed: String
}

type Query {
  cats: [Cat!]!
  cat(id: ID!): Cat
}

The schema is now the contract language. Resolvers must match these operation signatures.

Module Configuration

GraphQLModule.forRoot({
  driver: ApolloDriver,
  typePaths: ['./**/*.graphql'],
  definitions: {
    path: join(process.cwd(), 'src/graphql.ts'),
  },
})

• Schema-first is popular when GraphQL is designed with frontend stakeholders first.
• Generated TypeScript definitions help keep resolvers typed.
• You still implement Nest resolver classes for operations.
• Breaking schema changes are deliberate SDL edits rather than decorator side effects.

Schema-First Cheatsheet

Key options and workflow steps.

When Schema-First Fits Best

Choose schema-first when multiple clients negotiate the GraphQL contract up front, or when your team already thinks in SDL. Choose code-first when Nest/TypeScript speed of iteration is most important.

Federation and Contracts

Schema-first workflows often pair well with schema registries and federation gated by SDL review, though Nest supports both approaches depending on tooling.

Common Mistakes

• Editing generated TypeScript definitions by hand instead of regenerating.
• Letting resolvers diverge from SDL without CI checks.
• Keeping duplicate code-first decorators that fight schema-first SDL.
• Skipping nullability carefully—String vs String! changes client contracts.

Key Takeaways

• Schema-first makes GraphQL SDL the source of truth.
• typePaths loads .graphql files into Nest.
• Generated definitions keep resolvers typed to the schema.
• Pick code-first or schema-first deliberately for the team workflow.