GraphQL Fundamentals Skill

Name: graphql-fundamentals
Rating: 65
Author: pluginagentmarketplace

Master the building blocks of GraphQL APIs

Overview

This skill covers the essential GraphQL concepts every developer needs. From type definitions to query operations, you'll learn the foundation for building GraphQL APIs.

Quick Reference

Concept	Syntax	Example
Scalar	`String`, `Int`, `Float`, `Boolean`, `ID`	`name: String!`
Object	`type Name { fields }`	`type User { id: ID! }`
Input	`input Name { fields }`	`input CreateUserInput { name: String! }`
Enum	`enum Name { VALUES }`	`enum Status { ACTIVE INACTIVE }`
List	`[Type]` or `[Type!]!`	`tags: [String!]!`
Non-null	`Type!`	`id: ID!`

Core Concepts

1. Type System

graphql

# Scalar types (built-in)
type Example {
  id: ID!           # Unique identifier
  name: String!     # Text
  age: Int          # Integer (nullable)
  score: Float!     # Decimal
  active: Boolean!  # True/false
}

# Custom scalars
scalar DateTime
scalar JSON
scalar Upload

# Object types
type User {
  id: ID!
  email: String!
  profile: Profile    # Nested object
  posts: [Post!]!     # List of objects
}

type Profile {
  bio: String
  avatar: String
}

# Enums
enum UserRole {
  ADMIN
  EDITOR
  VIEWER
}

# Input types (for mutations)
input CreateUserInput {
  email: String!
  name: String!
  role: UserRole = VIEWER  # Default value
}

# Interfaces
interface Node {
  id: ID!
}

type User implements Node {
  id: ID!
  name: String!
}

# Unions
union SearchResult = User | Post | Comment

2. Queries

graphql

# Schema definition
type Query {
  # Single item
  user(id: ID!): User

  # List with optional filter
  users(filter: UserFilter, limit: Int = 10): [User!]!

  # Search
  search(query: String!): [SearchResult!]!
}

# Client query examples
query GetUser {
  user(id: "123") {
    id
    name
    email
  }
}

query GetUsersWithFilter {
  users(filter: { role: ADMIN }, limit: 5) {
    id
    name
  }
}

# With variables
query GetUser($userId: ID!) {
  user(id: $userId) {
    id
    name
  }
}
# Variables: { "userId": "123" }

# With aliases
query GetTwoUsers {
  admin: user(id: "1") { name }
  editor: user(id: "2") { name }
}

# With fragments
fragment UserFields on User {
  id
  name
  email
}

query GetUsers {
  users {
    ...UserFields
  }
}

3. Mutations

graphql

# Schema definition
type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): DeletePayload!
}

type CreateUserPayload {
  user: User
  errors: [Error!]!
}

# Client mutation
mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) {
    user {
      id
      name
    }
    errors {
      field
      message
    }
  }
}
# Variables: { "input": { "email": "test@example.com", "name": "Test" } }

4. Subscriptions

graphql

# Schema definition
type Subscription {
  userCreated: User!
  messageReceived(channelId: ID!): Message!
}

# Client subscription
subscription OnUserCreated {
  userCreated {
    id
    name
    createdAt
  }
}

subscription OnMessage($channelId: ID!) {
  messageReceived(channelId: $channelId) {
    id
    content
    sender { name }
  }
}

Common Patterns

Nullability Cheat Sheet

graphql

type Example {
  # Required field - never null
  id: ID!

  # Optional field - can be null
  nickname: String

  # Required list, optional items
  tags: [String]!        # [], ["a", null, "b"]

  # Required list, required items (most common)
  categories: [Category!]!  # [], [cat1, cat2]

  # Optional list (avoid - ambiguous)
  # items: [Item]  # null vs [] unclear
}

Input Validation Pattern

graphql

input CreateUserInput {
  email: String!      # Required
  name: String!       # Required
  age: Int            # Optional
  role: UserRole = VIEWER  # Optional with default
}

Troubleshooting

Error	Cause	Solution
`Cannot query field "x"`	Field not in schema	Check spelling, verify schema
`Variable "$x" not defined`	Missing variable declaration	Add to query signature
`Expected non-null, got null`	Resolver returned null for `!` field	Fix resolver or make nullable
`Unknown type "X"`	Type not defined	Add type definition

Debug Commands

bash

# Validate schema
npx graphql-inspector validate schema.graphql

# Introspect remote schema
npx graphql-inspector introspect http://localhost:4000/graphql

# Check for breaking changes
npx graphql-inspector diff old.graphql new.graphql

Usage

code

Skill("graphql-fundamentals")

Related Skills

•graphql-schema-design - Advanced schema patterns
•graphql-resolvers - Implementing resolvers
•graphql-codegen - TypeScript type generation

Related Agent

•01-graphql-fundamentals - For detailed guidance