gqlgen-plugin/

gqlgen Plugin Example

This example demonstrates how to use gqlscanner as a gqlgen plugin.

Setup

1. Install dependencies:

go get github.com/99designs/gqlgen
go get github.com/pablor21/gqlscanner/plugin

1. Create a tools.go file to ensure dependencies are tracked:

//go:build tools
// +build tools

package main

//go:generate go run generate.go

import (
    _ "github.com/99designs/gqlgen"
    _ "github.com/pablor21/gqlscanner/plugin"
)

1. Run go mod tidy:

go mod tidy

Files in This Example

• generate.go - Custom code generation entrypoint that registers the gqlscanner plugin
• gqlgen.yml - Standard gqlgen configuration (no plugins section!)
• tools.go - Ensures dependencies are tracked and adds go generate directive
• graph/models/ - Go structs with gql annotations that will be scanned

How It Works

1. Custom Generation Entrypoint (generate.go)

The plugin is registered in this file:

//go:build ignore
package main

import (
	"fmt"
	"os"
	"github.com/99designs/gqlgen/api"
	"github.com/99designs/gqlgen/codegen/config"
	"github.com/pablor21/gqlscanner/plugin"
)

func main() {
	cfg, err := config.LoadConfigFromDefaultLocations()
	if err != nil {
		fmt.Fprintln(os.Stderr, "failed to load config", err.Error())
		os.Exit(2)
	}

	// Register gqlscanner plugin
	p := plugin.New()
	p.Packages = []string{"./graph/models"}

	err = api.Generate(cfg, api.AddPlugin(p))
	if err != nil {
		fmt.Fprintln(os.Stderr, err.Error())
		os.Exit(3)
	}
}

2. Standard gqlgen Configuration (gqlgen.yml)

This file contains standard gqlgen configuration only:

schema:
  - graph/schema/*.graphql

exec:
  filename: graph/generated.go
  package: graph

model:
  filename: graph/model/models_gen.go
  package: model

resolver:
  layout: follow-schema
  dir: graph
  package: graph

# Note: No plugins: section here!
# Plugins are configured in generate.go

Usage

Generate GraphQL code:

go generate ./...

Or run the generate file directly:

go run generate.go

This will:

1. gqlscanner plugin runs first: Scans graph/models/ for Go structs with gql annotations
2. gqlscanner generates schemas: Creates GraphQL schema files in graph/schema/
3. gqlgen continues: Generates resolvers and types based on the schemas

Models

The graph/models/ directory contains example Go structs with gql annotations:

• product.go - Product and Category types

Example:

// gql.type
// Product represents a product in the catalog
type Product struct {
	ID          string  `json:"id"`
	Name        string  `json:"name"`
	Description string  `json:"description"`
	Price       float64 `json:"price"`
}

Plugin vs CLI

Workflow

1. Define Go structs with gql annotations in graph/models/
2. Run go generate ./...
3. gqlscanner generates schemas to graph/schema/
4. gqlgen generates resolvers and types
5. Implement resolver logic

Example Output

After running go generate ./..., you'll have:

graph/
├── generated.go          # gqlgen generated code
├── model/
│   └── models_gen.go     # Generated GraphQL models
├── models/
│   └── product.go        # Your Go structs (source)
├── schema/
│   └── product.graphql   # Generated by gqlscanner
└── *.resolvers.go        # Generated resolver stubs

Customizing Plugin Configuration

Modify generate.go to customize the plugin behavior:

p := plugin.New()

// Scan multiple packages
p.Packages = []string{
	"./graph/models",
	"./internal/domain",
}

// The plugin uses sensible defaults for:
// - Output directory: graph/schema/generated
// - Generation strategy: single file
// - Field naming: camelCase with json tags

For more advanced configuration options, see the plugin README.

Next Steps

• Read the plugin documentation for detailed usage
• See the main README for annotation syntax
• Explore the CLI example for standalone usage