105 Ways to Configure gqlgen.yml for Customization

Golang has long been a favorite for backend development thanks to its blazing performance and an ever-growing tooling ecosystem. One example: to build a GraphQL server in Go, we have gqlgen — a powerful and widely used framework. But did you know that gqlgen’s real power actually lives in its configuration file, gqlgen.yml?

In this article, I’ll break down 105 ways to configure gqlgen.yml, from the most essential ones all the way to hacky tweaks for your production-ready GraphQL API. Complete with code examples, mini simulations, and even a flow diagram with Mermaid. Ready? Let’s explore gqlgen.yml like a professional engineer!

What Is gqlgen.yml?

Before we dive into the 105 customizations, let’s refresh what this config file actually is:

• location: usually at the project root.
• purpose: defines the schema path, where resolvers live, type mappings, hooks, plugins, and various other tweaks.

The most basic example of gqlgen.yml:

 1# gqlgen.yml
 2schema:
 3  - graph/schema.graphqls
 4
 5exec:
 6  filename: graph/generated/generated.go
 7  package: generated
 8
 9model:
10  filename: graph/model/models_gen.go
11  package: model
12
13resolver:
14  layout: follow-schema
15  dir: graph/resolver
16  package: resolver

Configuring schema and Directory Structure

Ways #1-#5

1. Single Schema Path
   Point directly at the master schema file:

   yaml

   Copy

   1schema:
   2  - graph/schema.graphqls

2. Multiple Schema Files
   Split per module/microservice:

   yaml

   Copy

   1schema:
   2  - graph/user/schema.graphqls
   3  - graph/product/schema.graphqls

3. Globbing Schema Files
   Automatically load every schema in a folder:

   yaml

   Copy

   1schema:
   2  - "graph/**/*.graphqls"

4. Schema with Preprocessing
   Can be modified manually before generating.

5. Schema Versioning
   Split by version if your API is versioned.

Custom File and Package Output

Ways #6-#15

You can also customize the package name to make it more idiomatic.

1exec:
2  filename: internal/graph/gen.go
3  package: graphgen
4
5model:
6  filename: internal/graph/model.go
7  package: graphmodel

Type Mapping (models and bindings)

Ways #16-#25

This is the most powerful part!

Mapping GraphQL Types to Go Structs

For example, the schema:

1scalar DateTime
2type User {
3  id: ID!
4  createdAt: DateTime!
5}

Its mapping:

1models:
2  DateTime:
3    model:
4      - github.com/yourapp/pkg/datetime.Time

A few mapping options:

• model: change the type that is used
• bind: map to an imported type when scanning input
• field: per-field mapping

Optional: You can also set a custom mapping for array/matrix types.

Custom Unmarshal/Marshal for Scalars

Ways #26-#30

Default scalars are processed automatically. For custom scalars, you must create a Marshaller-Unmarshaller.

For example, mapping to time.Time:

1models:
2  DateTime:
3    model: time.Time
4    marshal: github.com/yourapp/pkg/datetime.MarshalDateTime
5    unmarshal: github.com/yourapp/pkg/datetime.UnmarshalDateTime

Defining Resolver Layouts

Ways #31-#35

1resolver:
2  layout: follow-schema
3  dir: graph/resolver
4  package: resolver

Layout options:

• follow-schema: Per-type, per-file (the most popular)
• single-file: All resolvers in a single file
• custom: A free-form path that you define yourself

Using Custom Plugins

Ways #36-#40

gqlgen supports third-party plugins to enhance the generated code:
For example, plugins for open-tracing, error-wrapping, or codegen compatible with GraphQL Federation.

1plugins:
2  - name: github.com/99designs/gqlgen/plugin/federation

Scalar and Directive Hooks

Ways #41-#55

Add custom hooks during the parsing process:

1directives:
2  upper:
3    implementation: github.com/yourapp/graph/directives.UpperCase
4    location: FIELD_DEFINITION

Custom scalar hooks can also add a validator or sanitizer to a custom scalar.

Custom Struct Tags (JSON/DB/CustomTag)

Ways #56-#65

Sometimes a field in GraphQL needs a different struct tag in Go.
Add the tag mapping through the config:

1# Creating a custom JSON tag
2models:
3  User:
4    fields:
5      email:
6        tag: json:"email,omitempty" db:"email_column"

The Same Tag for All Models

Ways #66-#69

1struct_tag: json

1struct_tag: json,db

Generating Interfaces

Ways #70-#75

For polymorphic schemas, use a mapping to a Go interface:

1models:
2  Animal:
3    model: github.com/yourapp/graph/model.Animal

Custom Null Options

Ways #76-#80

By default gqlgen uses a pointer *T for nullables. This can be changed to null.String, etc.:

1models:
2  String:
3    model: github.com/guregu/null.String

Mapping a Field to a Different Field

Ways #81-#90

For example, the schema:

1type Product {
2  id: ID!
3  productName: String!
4}

A Go struct with a different field name:

1type Product struct {
2  ID          string
3  NameOfProduct string
4}

Configure the mapping:

1models:
2  Product:
3    fields:
4      productName:
5        resolver: true
6        goField: NameOfProduct

Disabling/Enabling Output Artifacts

Ways #91-#95

Control which artifacts get generated through flags/config file:

1omit_getters: true
2omit_resolver_interface: false

Enabling Resolver Methods Only

Ways #96-#99

Reduce code by generating only the resolver portion:

1resolver:
2  only: true

Testing: Generating Mocks

Ways #100-#102

gqlgen can generate mocks for resolvers — very handy during unit testing!

1generate:
2  mocks: true

Environment and Relative Paths

Ways #103-#104

You can use env vars (for example, during CI/CD):

1schema:
2  - ${SCHEMA_PATH}

Watch Mode Auto Reload

Way #105

Enable live watch for UI or service development:

1gqlgen generate --watch

Simulation — The Codegen Pipeline

Below is an example of the codegen flow with a Mermaid diagram:

flowchart TD
    A[Update gqlgen.yml]
    B[Schema diubah]
    C[Run gqlgen generate]
    D[Generated Go Code Update]
    A-->C
    B-->C
    C-->D

flowchart TD
    A[Update gqlgen.yml]
    B[Schema diubah]
    C[Run gqlgen generate]
    D[Generated Go Code Update]
    A-->C
    B-->C
    C-->D

Summary

As you can see, gqlgen.yml isn’t just an ordinary template file.
From custom type and scalar mappings, plugins, and rapid testing, all the way to custom code layouts — everything is made flexible.

With the 105 methods above, you can customize your GraphQL API to fit your company’s needs, scale, and even the way your own team works. Don’t hesitate to experiment — and explore further through the documentation.
If there’s a customization tip I haven’t covered, share it in the comments!

Writing config correctly = producing clean, well-structured, and time-saving backend code.
#HappyCoding! 🚀

References

• gqlgen Configuration Reference
• GraphQL Official Spec
• Go Documentation