TypeGraphQL — Build GraphQL APIs with TypeScript Classes and Decorators

Introduction

TypeGraphQL is a code-first GraphQL framework for TypeScript that lets developers define schemas using classes and decorators. By leveraging TypeScript's type system and reflect-metadata, it generates the GraphQL schema from your code, ensuring the API types and resolver signatures stay in sync without maintaining a separate SDL file.

What TypeGraphQL Does

• Generates GraphQL schemas from TypeScript classes annotated with @ObjectType, @Field, and @InputType
• Defines resolvers using @Query, @Mutation, and @Subscription decorators on class methods
• Validates input automatically using class-validator decorators on input types
• Supports middleware, authorization guards, and dependency injection at the resolver level
• Integrates with Apollo Server, GraphQL Yoga, Express, Fastify, and other GraphQL servers

Architecture Overview

TypeGraphQL uses the reflect-metadata API to read TypeScript type information at runtime, then transforms decorated classes into a GraphQL schema using the graphql-js library. Resolvers are instantiated through a configurable dependency injection container (compatible with TypeDI, tsyringe, and others). Middleware functions wrap resolver execution in an onion-like chain, and authorization checks run before resolver methods via @Authorized decorators.

Self-Hosting & Configuration

• Enable experimentalDecorators and emitDecoratorMetadata in tsconfig.json
• Import reflect-metadata at the application entry point before any TypeGraphQL code
• Call buildSchema() with resolver classes to produce a GraphQL schema object
• Pass the built schema to any compatible GraphQL server (Apollo Server, Yoga, etc.)
• Configure a DI container via the container option in buildSchema for dependency injection

Key Features

• Single source of truth: TypeScript types define both the GraphQL schema and resolver signatures
• Built-in input validation via class-validator with automatic error formatting
• Authorization decorators with role-based and custom auth checker functions
• Generic types, interfaces, and inheritance for reusable schema patterns
• Subscription support with filtering and topic-based pub/sub integration

Comparison with Similar Tools

• Pothos (GraphQL Pothos) — code-first schema builder using a fluent API; TypeGraphQL uses class decorators and OOP patterns
• Nexus — code-first schema construction with a chainable API; TypeGraphQL relies on TypeScript decorators and metadata
• SDL-first approach — writing .graphql files separately; TypeGraphQL keeps types and resolvers co-located in code
• GraphQL Code Generator — generates TypeScript types from existing SDL; TypeGraphQL works in the opposite direction
• tRPC — type-safe RPC without GraphQL; TypeGraphQL provides a full GraphQL API layer with schema introspection

FAQ

Q: Do I still need to write a .graphql schema file? A: No. TypeGraphQL generates the GraphQL schema from your TypeScript classes and decorators. You can optionally emit the SDL for documentation.

Q: Can I use TypeGraphQL with Prisma? A: Yes. Community integrations like typegraphql-prisma auto-generate TypeGraphQL types from your Prisma schema for rapid CRUD API development.

Q: Does TypeGraphQL support subscriptions? A: Yes. Use the @Subscription decorator with topic and filter functions, compatible with graphql-subscriptions or any PubSub implementation.

Q: How does it handle N+1 query problems? A: TypeGraphQL integrates with DataLoader through middleware or field resolvers to batch and cache database queries automatically.

Sources

• https://github.com/MichalLytek/type-graphql
• https://typegraphql.com/docs/introduction.html