grx

grx is a fast, lightweight GraphQL server and runtime for Go. You write plain Go structs and methods; grx turns them into an executable GraphQL schema — no SDL files, no code generation — and serves it as an ordinary http.Handler.

• Code-first schema — exported structs are object types, methods on Query, Mutation and Subscription are resolvers, and gql struct tags set names and nullability.
• Queries, mutations and subscriptions over HTTP, WebSocket (graphql-transport-ws) and Server-Sent Events.
• Plain net/http — mount it on the standard mux, Chi, Gin, Echo or Fiber.
• Production controls — request and depth limits, timeouts, persisted queries, operation and field authorizers, introspection toggles, gzip, plugins and middleware.

Install

go get github.com/grx-gql/grx@latest

Requires Go 1.25 or newer.

Quick start

package main

import (
	"context"
	"log"
	"net/http"

	"github.com/grx-gql/grx"
	"github.com/grx-gql/grx/schema"
)

type User struct {
	ID   string `gql:"id,nonNull"`
	Name string `gql:"name,nonNull"`
}

type UserArgs struct {
	ID string `gql:"id,nonNull"`
}

type Query struct{}

// User becomes the `user(id: String!): User` field on Query.
func (Query) User(ctx context.Context, args UserArgs) (*User, error) {
	return &User{ID: args.ID, Name: "Ada Lovelace"}, nil
}

func main() {
	server, err := grx.NewServer(
		grx.WithSchema(schema.Config{Query: Query{}}),
		grx.WithPlaygroundPath("/"),
	)
	if err != nil {
		log.Fatal(err)
	}

	log.Println("playground on http://localhost:4000/, GraphQL on POST /graphql")
	log.Fatal(http.ListenAndServe(":4000", server))
}

Run it with go run ., open http://localhost:4000/ and query:

{
  user(id: "1") {
    id
    name
  }
}

Examples

Runnable examples live in examples/:

go run ./examples/basic           # queries, mutations, plugins
go run ./examples/subscriptions   # pub/sub over WebSocket and SSE
go run ./examples/sse             # SSE-only subscriptions, no WebSocket
go run ./examples/auth            # bearer auth, context identity, field authorizer

Tagged Go module releases (no binaries). The nested redis module is not in release-please — tag redis/v* yourself (the same workflow warms proxy.golang.org for those tags).

Pub/Sub API migration

The current pub/sub API is byte-oriented and backend-neutral. Import github.com/grx-gql/grx/pubsub for the PubSub contract, github.com/grx-gql/grx/pubsub/memory for the in-process backend, or github.com/grx-gql/grx/pubsub/redis for the separate Redis module. The former the former legacy pub/sub package paths, typed wrapper, codecs, and filters are no longer part of the public API; encode domain values in resolvers before publishing and decode them after subscribing.

There are also examples for directives, enums, interfaces and unions, custom scalars and file uploads.

Documentation

The full documentation is at https://grx-gql.github.io/grx/:

• Get started — a first server, and mounting it on your router
• Define your schema — types, lists, enums, unions and inputs
• Subscriptions — pub/sub, WebSocket and SSE
• Security and Deployment — going to production
• API reference on pkg.go.dev

grx is in active development and does not yet cover the whole GraphQL specification; ROADMAP.md tracks what is missing.

Contributing

See CONTRIBUTING.md.

License

MIT