GraphQL & Apollo Expert

English | Bahasa Indonesia

---

English

Orchestration & Integration

Connects and orchestrates with relevant domain skills like brainstorming, zero-to-prod-orchestrator, and project-context-mapper to ensure cohesive execution.

Description

Production-grade guidance for building and consuming GraphQL APIs. Focuses on the Apollo ecosystem (Apollo Server, Apollo Client, Federation), NestJS GraphQL integration, and solving common performance pitfalls like the N+1 query problem using DataLoaders.

Trigger Conditions

Activate this skill when the user is:

• Setting up a GraphQL server with NestJS, Express, or Apollo Server.
• Using @apollo/client or @vue/apollo-composable on the frontend.
• Deciding between Code-First vs. Schema-First GraphQL design.
• Optimizing backend database queries triggered by GraphQL resolvers (N+1 problem).
• Implementing GraphQL Subscriptions via WebSockets.

Core Concepts

1. Code-First vs Schema-First (NestJS)

• Code-First (Recommended for TypeScript): Define resolvers and object types using TS decorators. The schema .gql file is automatically generated. Ensures a single source of truth.
• Schema-First: Write raw .gql files and use tools to generate TypeScript interfaces.

// NestJS Code-First Example
import { ObjectType, Field, Int } from '@nestjs/graphql';

@ObjectType()
export class User {
  @Field(() => Int)
  id: number;

  @Field()
  email: string;
}

import { Resolver, Query } from '@nestjs/graphql';

@Resolver(() => User)
export class UserResolver {
  @Query(() => [User])
  async users(): Promise<User[]> {
    return [{ id: 1, email: 'user@example.com' }];
  }
}

2. The N+1 Problem & DataLoader

GraphQL's resolver architecture easily causes the N+1 query problem (e.g., querying authors and their posts results in 1 query for authors, and N queries for each author's posts). Solution: Always use DataLoader to batch and cache database requests within a single GraphQL execution tick.

3. Apollo Client (Frontend)

Use Apollo Client for robust caching and normalized state management on the frontend.

import { useQuery, gql } from '@apollo/client';

const GET_USERS = gql`
  query GetUsers {
    users {
      id
      email
    }
  }
`;

function UserList() {
  const { loading, error, data } = useQuery(GET_USERS);
  if (loading) return <p>Loading...</p>;
  return <div>{data.users[0].email}</div>;
}

Integration with Other Skills (MANDATORY)

This skill works best when combined with:

• js-backend-expert — For setting up the underlying Node.js/NestJS server architecture.
• database-orm-expert — For connecting Prisma/Drizzle ORM directly to GraphQL resolvers and DataLoaders.
• senior-frontend / vue-frontend-expert — For integrating Apollo Client into React or Vue applications.

Referenced By Orchestrators (MANDATORY)

• brainstorming — Add to "API Design & Contracts".
• zero-to-prod-orchestrator — Phase 4 (Backend APIs).

---

Bahasa Indonesia

Integrasi Orkestrasi

Terhubung dan mengorkestrasi skill domain yang relevan seperti brainstorming, zero-to-prod-orchestrator, dan project-context-mapper untuk memastikan eksekusi yang kohesif.

Deskripsi

Panduan produksi untuk membangun dan mengkonsumsi API GraphQL. Mencakup ekosistem Apollo, NestJS GraphQL, dan teknik optimasi performa seperti DataLoader.

Kondisi Pemicu

• Saat mengkonfigurasi server GraphQL menggunakan NestJS atau Apollo.
• Saat menggunakan Apollo Client di aplikasi React atau Vue.
• Saat menghadapi masalah performa N+1 query pada resolusi data.

Panduan Singkat

• Pilih Code-First di TypeScript: Di NestJS atau TypeScript murni, gunakan pendekatan Code-First (@nestjs/graphql atau TypeGraphQL) agar Anda tidak perlu mengelola file .gql dan interface TS secara terpisah.
• Gunakan DataLoader Wajib: Jangan pernah melakukan query database langsung di dalam resolver yang mengembalikan list of objects bersarang. Gunakan DataLoader dari Facebook untuk mengumpulkan (batching) request database.
• Frontend Caching: Manfaatkan normalisasi cache bawaan Apollo Client agar Anda tidak perlu menggunakan Redux atau state manager lain untuk menyimpan data dari server.