Getting Started

This guide will help you get started with Type GraphQL Query in your Plus261 project. You’ll learn how to create your first DTO, configure a module, and build a GraphQL schema.

What You’ll Learn

By the end of this guide, you’ll be able to:

✅ Set up Type GraphQL Query in your project
✅ Create your first DTO (Data Transfer Object)
✅ Configure a module with automatic resolvers
✅ Build a GraphQL schema
✅ Understand the basic concepts

Prerequisites

Before starting, make sure you have:

TypeScript - Basic TypeScript knowledge
GraphQL - Basic understanding of GraphQL concepts
Decorators - Familiarity with TypeScript decorators
Node.js/Bun - Runtime environment

Installation

Install Dependencies

Install the required packages:

```bash bun add type-graphql graphql reflect-metadata ```

Configure TypeScript

Enable decorators in your tsconfig.json file.

Import Reflect Metadata

Add at the top of your entry file:

```typescript import "reflect-metadata"; ```

TypeScript Configuration

Add the following to your tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Basic Example

Let’s create a simple example to get you started. We’ll create a User type with automatic CRUD operations.

Step 1: Create a DTO

Create your first GraphQL type:

import { ObjectType, Field, ID } from '@lib/type-graphql';
import { IDField, EnhancedField } from '@lib/type-graphql-query';

@ObjectType()
export class User {
  @IDField(() => ID)
  id!: string;

  @EnhancedField(() => String)
  name!: string;

  @EnhancedField(() => String)
  email!: string;
}

Step 2: Create a Module

Create a module configuration that automatically generates CRUD resolvers:

import { TypeGraphqlQueryOptions } from '@lib/type-graphql-query';
import { User } from './dto/user.type';
import { user as userTable } from '@lib/db';

const resolvers = [
  {
    DTOClass: User,
    Entity: userTable,
  },
] satisfies TypeGraphqlQueryOptions['resolvers'];

export default resolvers;

Step 3: Build Schema

Build your GraphQL schema using buildTypeDefsAndResolvers:

import { buildTypeDefsAndResolvers } from '@lib/type-graphql-query';
import { withDrizzle } from '@lib/drizzle-query';
import { withTypedi } from '@lib/typedi-query';
import { db } from '../database';
import userModuleResolvers from './user/user.module';

const { resolvers, typeDefs } = await buildTypeDefsAndResolvers(
  withTypedi(
    withDrizzle({
      resolvers: [...userModuleResolvers],
      database: db,
    }),
  ),
);

What You Get

Once configured, Type GraphQL Query automatically generates:

Feature	Description
🔍 Queries	`findOneUser`, `users` (with filtering, sorting, paging)
✏️ Mutations	`createOneUser`, `updateOneUser`, `deleteOneUser`, `upsertOneUser`
🔄 Subscriptions	Real-time updates (if enabled)
🔐 Authorization	Permission checks (if configured)
📊 Aggregations	Aggregate queries (if enabled)

Testing Your Setup

1. Start Your Server

cd apps/api
bun dev

2. Open GraphQL Playground

Navigate to http://localhost:4000/graphql and try a query:

query {
  users {
    nodes {
      id
      name
      email
    }
    totalCount
  }
}

3. Try a Mutation

mutation {
  createOneUser(input: { name: "John Doe", email: "john@example.com" }) {
    id
    name
    email
  }
}

Quick Reference

Task	Documentation
Create DTOs	DTOs Guide
Configure Modules	Resolvers Guide
Add Queries	Queries Guide
Add Mutations	Mutations Guide
Add Relations	Relations Guide
Add Authorization	Authorization Guide

Next Steps

Continue your learning journey:

📝 DTOs - Learn about DTO definitions and decorators
🔍 Queries - Understand query operations with filtering and sorting
✏️ Mutations - Learn about data modifications
🔗 Relations - Manage relationships between entities

Type GraphQL Query Overview - Complete overview
Code Structure - Understand module organization
API Overview - Learn about the API architecture
Development Guide - Development workflow