Migration Guide

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)
    }
    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. See Code Generation for details.

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

• MIGRATION.md — comprehensive migration guide in the main repo
• Code Generation — full codegen DSL reference
• Switching to Codegen — migrate from asset-based to codegen
• Getting Started — quick start guide
• Home — project overview