rails-graphql-patterns

ag0os's avatarfrom ag0os

GraphQL patterns for Rails applications using graphql-ruby gem. Automatically invoked when working with GraphQL schemas, types, resolvers, mutations, subscriptions, or the app/graphql directory. Triggers on "GraphQL", "schema", "resolver", "mutation", "query type", "subscription", "graphql-ruby", "field", "argument", "N+1 graphql", "dataloader".

⭐2stars🔀0forks📁View on GitHub🕐Updated Jan 8, 2026

When & Why to Use This Skill

The rails-graphql-patterns skill is a specialized toolkit designed to streamline the development of GraphQL APIs within Ruby on Rails applications. By leveraging the graphql-ruby gem, it provides standardized architectural patterns for schema design, type definitions, and complex mutations. It focuses on best practices such as type safety, efficient data fetching via DataLoader to eliminate N+1 queries, and structured error handling, ensuring a scalable and performant API layer.

Use Cases

  • Designing and organizing type-safe GraphQL schemas and object types within the app/graphql directory.
  • Implementing complex mutations with robust argument validation, authorization checks, and structured error responses.
  • Optimizing database performance by applying DataLoader patterns to batch-load records and prevent N+1 query issues.
  • Setting up real-time subscriptions and advanced query resolvers for high-performance Rails backends.
  • Refactoring legacy REST endpoints into a clean, maintainable GraphQL architecture using industry-standard Ruby patterns.
namerails-graphql-patterns
descriptionGraphQL patterns for Rails applications using graphql-ruby gem. Automatically invoked when working with GraphQL schemas, types, resolvers, mutations, subscriptions, or the app/graphql directory. Triggers on "GraphQL", "schema", "resolver", "mutation", "query type", "subscription", "graphql-ruby", "field", "argument", "N+1 graphql", "dataloader".
allowed-toolsRead, Grep, Glob

Rails GraphQL Patterns

Patterns for building GraphQL APIs in Rails applications using graphql-ruby.

When This Skill Applies

  • Designing GraphQL schemas and types
  • Implementing resolvers and mutations
  • Optimizing queries and preventing N+1 problems
  • Handling authentication/authorization in GraphQL
  • Implementing subscriptions for real-time updates
  • Structuring the app/graphql directory

Quick Reference

Component Purpose Location
Types Define object shapes app/graphql/types/
Queries Read operations app/graphql/types/query_type.rb
Mutations Write operations app/graphql/mutations/
Resolvers Query logic app/graphql/resolvers/
Sources DataLoader batching app/graphql/sources/

Detailed Documentation

  • patterns.md - Complete GraphQL patterns with examples

Type Definition Basics

# app/graphql/types/user_type.rb
module Types
  class UserType < Types::BaseObject
    field :id, ID, null: false
    field :email, String, null: false
    field :name, String
    field :created_at, GraphQL::Types::ISO8601DateTime, null: false

    field :posts, [Types::PostType], null: true
    field :posts_count, Integer, null: false

    def posts_count
      object.posts.size  # Use size for counter cache
    end
  end
end

Mutation Basics

# app/graphql/mutations/create_post.rb
module Mutations
  class CreatePost < BaseMutation
    argument :title, String, required: true
    argument :content, String, required: true

    field :post, Types::PostType
    field :errors, [String], null: false

    def resolve(title:, content:)
      post = context[:current_user].posts.build(title: title, content: content)

      if post.save
        { post: post, errors: [] }
      else
        { post: nil, errors: post.errors.full_messages }
      end
    end
  end
end

N+1 Prevention with DataLoader

# app/graphql/sources/record_loader.rb
class Sources::RecordLoader < GraphQL::Dataloader::Source
  def initialize(model_class)
    @model_class = model_class
  end

  def fetch(ids)
    records = @model_class.where(id: ids).index_by(&:id)
    ids.map { |id| records[id] }
  end
end

# Usage in type
def author
  dataloader.with(Sources::RecordLoader, User).load(object.user_id)
end

Key Principles

  • Type Safety: Define explicit types for all fields
  • Null Handling: Be intentional about null: true/false
  • Batch Loading: Use DataLoader to prevent N+1 queries
  • Authorization: Check permissions at field level
  • Error Handling: Return structured errors, not exceptions