Skip to main content
Rails GraphQL is distributed as a Ruby gem and integrates seamlessly with Rails applications. This guide covers installation, configuration, and verification.

​
Requirements

Before installing Rails GraphQL, ensure your environment meets these requirements:

Rails

Rails 6.0 or higherRails GraphQL is built to integrate with modern Rails conventions

Ruby

Ruby 2.6.3 or higherRequired for the C-based parser to compile correctly
Rails GraphQL uses a custom C-based parser for exceptional performance. The gem will compile native extensions during installation.

​
Installation

1

Add the gem

Add Rails GraphQL to your Gemfile:
bundle add rails-graphql
Or add it manually to your Gemfile:
Gemfile
gem 'rails-graphql'
Then install:
bundle install
2

Run the generator

Rails GraphQL provides a generator to set up the basic structure:
rails g graphql:install
This generator creates:
  • app/graphql/app_schema.rb - Your main GraphQL schema
  • app/controllers/graphql_controller.rb - Controller for handling GraphQL requests
  • Route configuration in config/routes.rb
The install generator is a shortcut that runs both graphql:schema and graphql:controller generators. You can run them separately if needed.
3

Configure the route

The generator adds a route to config/routes.rb:
config/routes.rb
Rails.application.routes.draw do
  post '/graphql', to: 'graphql#execute'
end
You can customize the endpoint path as needed:
config/routes.rb
post '/api/graphql', to: 'graphql#execute'
# or
post '/api/v1/graphql', to: 'graphql#execute'
4

Verify installation

Start your Rails server and verify the installation:
rails server
Test the endpoint with a simple introspection query:
curl -d '{"query":"{ __typename }"}' \
     -H "Content-Type: application/json" \
     -X POST http://localhost:3000/graphql
You should receive:
{"data":{"__typename":"Query"}}

​
Directory structure

After installation, your GraphQL code lives in app/graphql/. This directory works differently from standard Rails folders: 
/ app
  / graphql            # Consider this the root of your GraphQL app
    - app_schema.rb    # Your main schema
    / objects          # GraphQL object types
    / inputs           # Input types for mutations
    / interfaces       # Interface types
    / unions           # Union types
    / enums            # Enum types
    / scalars          # Custom scalar types
    / queries          # Query field definitions
    / mutations        # Mutation field definitions
    / subscriptions    # Subscription field definitions
    / sources          # ActiveRecord bridges
    / directives       # Custom directives
    / fields           # Reusable field definitions
These directories are not created automatically. Create them as needed when organizing your GraphQL schema.

​
Module structure

All GraphQL classes must be inside the GraphQL module to avoid naming collisions:
app/graphql/objects/user.rb
# Correct
class GraphQL::User < GraphQL::Object
end

# Not: class User < GraphQL::Object
This structure is 100% compatible with Zeitwerk, Rails’ autoloader.

​
Configuration options

Rails GraphQL provides several configuration options. Create an initializer to customize behavior:
config/initializers/graphql.rb
Rails::GraphQL.configure do |config|
  # Enable or disable introspection (disable in production for security)
  config.enable_introspection = true

  # Set cache store (defaults to Rails.cache)
  config.cache = ActiveSupport::Cache::MemoryStore.new

  # Default response format (:hash or :json)
  config.default_response_format = :hash

  # Enable string collector for better performance
  config.enable_string_collector = true
end

​
Schema-specific configuration

You can also configure individual schemas:
app/graphql/app_schema.rb
module GraphQL
  class AppSchema < GraphQL::Schema
    # Configure this schema
    config.enable_introspection = false
    config.cache = CustomCacheStore.new

    # Define your fields...
  end
end

​
Controller setup

The generated controller includes the GraphQL::Controller module:
app/controllers/graphql_controller.rb
class GraphQLController < ApplicationController
  include GraphQL::Controller

  # Skip CSRF token verification for API requests
  skip_before_action :verify_authenticity_token
end
Only skip CSRF token verification if your GraphQL endpoint is intended as an API. If you’re using GraphQL with web forms, keep CSRF protection enabled.

​
Adding authentication

You can add authentication to your GraphQL controller:
app/controllers/graphql_controller.rb
class GraphQLController < ApplicationController
  include GraphQL::Controller

  before_action :authenticate_user!
  skip_before_action :verify_authenticity_token

  private

  def graphql_context
    { current_user: current_user }
  end
end

​
Using generators

Rails GraphQL provides several generators to speed up development: 
# Generate a schema
rails g graphql:schema

# Generate a controller
rails g graphql:controller

# Generate an object type
rails g graphql:object User

# Generate a mutation
rails g graphql:mutation CreateUser

# Generate a query
rails g graphql:query Users
Run rails g to see all available GraphQL generators.

​
Next steps

Now that Rails GraphQL is installed, you’re ready to build your first schema:

Quickstart

Build your first GraphQL query

Architecture

Understand how Rails GraphQL works

Build docs developers (and LLMs) love

Get started for freeTalk to us