Getting Started

Installation


npm install @gqlkit-ts/runtime @graphql-tools/schema graphql
npm install -D @gqlkit-ts/cli


pnpm add @gqlkit-ts/runtime @graphql-tools/schema graphql
pnpm add -D @gqlkit-ts/cli


yarn add @gqlkit-ts/runtime @graphql-tools/schema graphql
yarn add -D @gqlkit-ts/cli

Tip

If you use AI coding agents like Claude Code or Codex, run gqlkit docs to set up gqlkit skills. See Coding Agents for details.

Project Structure

gqlkit expects your types and resolvers to be in src/gqlkit/schema/:


src/
└── gqlkit/
    ├── context.ts       # Context type definition
    ├── gqlkit.ts        # Resolver factories
    └── schema/
        ├── user.ts      # User type and resolvers
        ├── post.ts      # Post type and resolvers
        └── query.ts     # Query resolvers

Set Up Context and Resolver Factories

Create src/gqlkit/context.ts to define your context type:


export type Context = {
  currentUser: { id: string; name: string; email: string | null } | null;
};

Create src/gqlkit/gqlkit.ts to export resolver factories:


import { createGqlkitApis } from "@gqlkit-ts/runtime";
import type { Context } from "./context";
 
export const { defineQuery, defineMutation, defineSubscription, defineField } =
  createGqlkitApis<Context>();

Define Your First Type and Query

Create a simple User type and query in src/gqlkit/schema/user.ts:


import { defineQuery } from "../gqlkit";
import type { NoArgs } from "@gqlkit-ts/runtime";
 
export type User = {
  id: string;
  name: string;
  email: string | null;
};
 
// NoArgs indicates this query takes no arguments
export const me = defineQuery<NoArgs, User | null>(
  (_root, _args, ctx) => ctx.currentUser
);

Generate Schema

Run the generator:


npm exec gqlkit gen


pnpm gqlkit gen


yarn gqlkit gen

This will create files in src/gqlkit/__generated__/:

schema.ts - GraphQL schema AST (DocumentNode)
resolvers.ts - Resolver map

Create GraphQL Schema

Use @graphql-tools/schema to combine the generated outputs into an executable schema:


import { makeExecutableSchema } from "@graphql-tools/schema";
import { typeDefs } from "./gqlkit/__generated__/schema";
import { resolvers } from "./gqlkit/__generated__/resolvers";
 
export const schema = makeExecutableSchema({ typeDefs, resolvers });

Next Steps

HTTP Server Integration - Connect your schema to graphql-yoga, Apollo Server, or other HTTP servers
Object Types - Learn more about defining types
Queries & Mutations - Advanced resolver patterns
Subscriptions - Real-time data with subscriptions