TypeGraphQL: Building GraphQL Schemas from TypeScript Classes

The redundancy TypeGraphQL removes from a TypeScript GraphQL API

The README frames the problem precisely: in a typical Node.js GraphQL service you write the schema in schema.graphql, write ORM entity classes, then write TypeScript interfaces for arguments and inputs, and only then write resolvers. Adding one field means editing several files, and the rename feature in your editor will not follow the field across the SDL. The project's stated goal is a single source of truth: define the schema with classes and decorators, and let the library derive the SDL from them.

The audience is TypeScript teams already committed to classes, decorators and a dependency injection container. If your codebase is functional and avoids decorators, the library's central mechanism works against your style. The README also notes that code generation tools such as GraphQL Code Generator and graphqlgen solve only half the problem: they generate interfaces and resolver skeletons from an existing schema but leave the schema-to-model duplication in place.

How decorators become an SDL schema

The mechanism is metadata plus a schema builder. You annotate a class with @ObjectType() and its properties with @Field(), and the README shows the resulting SDL fragment: id: ID!, title: String!, ratings: [Rate!]!, averageRating: Float. The type function passed to @Field, as in @Field(type => ID), is how the library resolves the GraphQL type when the TypeScript type alone is not enough.

Resolvers are classes too, marked with @Resolver(Recipe). A constructor parameter can be injected by a DI container, @Query and @Mutation register operations, @Arg binds arguments, @FieldResolver computes a field from the root object, and @Authorized(Roles.Admin) acts as an auth guard on a mutation. The README's example turns a RecipeResolver class into Query.recipes and Mutation.removeRecipe in SDL. The repository ships an examples directory with entries for TypeORM, MikroORM, Typegoose, tsyringe, Apollo Federation, subscriptions and query complexity, which is where the integration patterns actually live. The benchmarks directory and a tests folder are also present at the top level.

Installing TypeGraphQL and writing a first resolver

The README points to the website for the installation guide and the getting started walkthrough rather than listing install commands inline, so the package name from package.json is the reliable anchor: the npm package is type-graphql. The current published version in the repository manifest is 2.0.0-rc.4.

A first use follows the README's own shape. Define an object type, then a resolver class, then pass the resolver array to the schema builder. The README names the builder as buildSchema in the related terminology, and the getting started docs cover the exact call.

@ObjectType()
class Recipe {
  @Field(type => ID)
  id: string;

  @Field()
  title: string;
}

This class produces the SDL type Recipe with a non-null ID and a non-null String, matching the README's example. Note the explicit type function on id: without it the library cannot know the field is an ID rather than a String.

@Resolver(Recipe)
class RecipeResolver {
  constructor(private recipeService: RecipeService) {}

  @Query(returns => [Recipe])
  recipes() {
    return this.recipeService.findAll();
  }
}

The constructor parameter is the dependency injection hook the README describes. The query returns the array the service provides, and the schema gains Query.recipes: [Recipe!]!. What you should see after building the schema is an SDL document containing both the Recipe type and the recipes query, with no hand-written schema.graphql anywhere in the project.

Release candidate status and the stable 1.0.0 claim

This is the part to read carefully before pinning a version. The repository manifest declares version 2.0.0-rc.4, and the release list shows v2.0.0-rc.4 on 2026-02-26, v2.0.0-rc.3 on 2026-02-08 and v2.0.0-rc.2 on 2024-06-07. A two-year gap between rc.2 and rc.3 is worth noting if you plan to depend on the 2.0 line.

The README's future section still says the currently released version is a stable 1.0.0 release with 97% coverage and roughly 500 test cases. That text and the 2.0.0-rc.4 manifest do not describe the same state, and the README does not explain the discrepancy. Treat the README's stability claims as describing the 1.x line, and check the changelog and the npm tag before you install. The repository is not archived, and the last push was on 2026-07-16.

Where the decorator approach is the wrong tool

Decorator metadata depends on the TypeScript compiler emitting it and on reflection being available at runtime. That is a build configuration constraint the README does not spell out in its introduction, but it is inherent to the approach: if your toolchain strips metadata or your transpiler does not support decorators, the schema builder has nothing to read.

The sharper limitation is schema-first workflows. If your organization treats the SDL file as the contract, reviews schema changes as text, and feeds that file to codegen for non-TypeScript clients, TypeGraphQL inverts the direction of truth. The schema becomes an output, not an input. The README is explicit that codegen tools solve the interface-generation half of the problem, which is exactly the half TypeGraphQL replaces. Teams whose iOS, Android and TypeScript clients all consume one checked-in schema will find the generated schema harder to diff and review than the file they maintain by hand.

TypeGraphQL compared with Nexus and plain graphql-js

The README names GraphQL Code Generator and graphqlgen as the tools it improves on, and the difference is the direction of generation. Codegen reads an SDL schema and writes TypeScript types. TypeGraphQL reads TypeScript classes and writes the schema. One keeps the SDL authoritative; the other keeps the classes authoritative.

Against plain graphql-js, the difference is boilerplate and cross-cutting concerns. The README's comparison shows a raw resolver doing repository lookup, container access, Joi validation and an auth check before the business logic, and presents @Authorized, dependency injection and validation decorators as replacements for that repeated block. That is a real reduction in per-resolver code, but it also means authorization and validation become declarative attributes on a method rather than visible statements inside it. Some teams prefer the explicit version precisely because the control flow is readable in one place. The repository's authorization, automatic-validation and custom-validation examples are the place to judge which style suits you.

Editorial conclusion

Adopt TypeGraphQL when your schema is already expressed as TypeScript classes and you want decorators, dependency injection and Authorized guards in the same file as the fields. Do not adopt it if you want a schema-first SDL file that non-TypeScript clients or codegen tools read directly, or if a release candidate in production is unacceptable. Before committing, verify the version you install against the npm 2.0.0-rc.4 tag, confirm your decorator and metadata-reflection settings compile, and check that the GraphQL server version you already run matches what the current release expects.

Frequently asked questions

Official sources

1. License: MIT
2. MichalLytek/type-graphql on GitHub
3. Project website
4. README
5. Releases