Skip to content

Migration Guide

Jump to bottom
Maxwell edited this page Jul 24, 2026 · 4 revisions

Migration Guide: From :library to Modular Dependencies

retrofit-graphql v2.x introduces a modular architecture. The old :library module is now a deprecated backward-compatible aggregator. This guide shows how to migrate your project.

Quick Migration: Drop-in Replacement

If you use all library features and want no code changes:

// Old
dependencies {
    implementation("com.github.anitrend:retrofit-graphql:2.x")
}

// New — same artifact, same API. Deprecated but fully functional.
dependencies {
    implementation("com.github.anitrend:retrofit-graphql:2.x")
}

The aggregator is deprecated but will receive critical fixes for the foreseeable future.

Recommended: Direct Module Dependencies

Migrate to individual modules for smaller build footprint and clearer dependencies:

// Asset-based GraphQL queries (traditional approach)
dependencies {
    implementation(project(":runtime"))        // Retrofit converter
    implementation(project(":api"))            // QueryContainerBuilder, GraphQLOperation
    implementation(project(":android-assets")) // GraphProcessor, asset discovery
    implementation(project(":annotations"))    // @GraphQuery annotation
}

New: Code Generation Plugin

v2.x adds optional build-time code generation:

plugins {
    id("co.anitrend.retrofit.graphql.codegen") version "2.x"
}

dependencies {
    implementation(project(":runtime"))
    implementation(project(":api"))
    // :annotations and :android-assets NOT required for codegen-only consumers
    // (they are pulled transitively via :runtime)
}

retrofitGraphQL {
    packageName.set("your.package.generated")
    schema.set(file("src/main/graphql/schema.graphql"))
    operations.from(fileTree("src/main/graphql") {
        include("**/*.graphql")
    })
    common {
        generateVariables.set(true)
        generateResponses.set(true) // optional response model generation
    }
    scalars {
        map("DateTime", "kotlin.String")
        map("GitObjectID", "kotlin.String")
    }
}

Move your .graphql files from assets/graphql/ to src/main/graphql/.

Generated output includes GeneratedGraphQLRegistry that you wire into your converter:

val factory = GraphConverter.create(
    context = androidContext(),
    registry = GeneratedGraphQLRegistry,
)

When generateVariables = true, the plugin also generates variable classes, input object classes, and .request(...) factory methods. When generateResponses = true, it also generates operation-scoped {OperationName}Data response model classes. See Code Generation for details.

Generated response models are operation-scoped, not schema-wide. They preserve aliases, conditional nullable fields, and GraphQL interface or union branches using sealed interfaces with __typename-based polymorphism.

Import Changes

Old (io.github.wax911.library.*) New (co.anitrend.retrofit.graphql.*)
io.github.wax911.library.annotation.GraphQuery co.anitrend.retrofit.graphql.annotation.GraphQuery
io.github.wax911.library.converter.GraphConverter co.anitrend.retrofit.graphql.converter.GraphConverter
io.github.wax911.library.model.body.GraphContainer co.anitrend.retrofit.graphql.model.body.GraphContainer
io.github.wax911.library.model.request.QueryContainerBuilder co.anitrend.retrofit.graphql.model.request.QueryContainerBuilder

Module Reference

Module Purpose Required for codegen?
:annotations @GraphQuery annotation No (only for asset-based queries)
:api Public API interfaces and models Yes
:runtime Retrofit Converter.Factory Yes
:android-assets Asset-based query discovery No (use codegen instead)
:codegen-core Code generation engine Plugin dependency
:gradle-plugin Gradle plugin for codegen Plugin dependency
:serialization-gson Gson-backed serialization No (use Retrofit's Gson converter directly)
:serialization-kotlinx kotlinx.serialization backend No

Further Reading

Clone this wiki locally