Provides

This annotation is used on callable declarations in a class to provide instances of a given type to dependency graph. Any class or interface can define providers, but they will not be included unless they are or are a supertype of a DependencyGraph-annotated type.

@DependencyGraph
interface AppGraph : NetworkProviders {
  @Provides val string: String get() = "Hello, world!"
}

// Inherited by AppGraph
interface NetworkProviders {
  @Provides fun provideHttpClient(): HttpClient = HttpClient()
}

Providers are lazily evaluated, at runtime they are always wrapped up in Provider (the default) or Lazy (if scoped).

Provider callables must have explicit return types, it is an error to have an implicit return type.

Provider callables may not return nullable types. This may change in the future, see this discussion.

Provides can declare dependencies as parameters to their functions.

interface NetworkProviders {
  @Provides fun provideHttpClient(cache: Cache): HttpClient = HttpClient(cache)
}

Dependencies may also be wrapped in Provider or Lazy as needed and the Metro compiler will automatically manage them during injection.

interface NetworkProviders {
  @Provides fun provideHttpClient(lazyCache: Lazy<Cache>): HttpClient = HttpClient(lazyCache)
}

If a provider is scoped, it will be managed by the consuming graph as a lazily-evaluated singleton within that scope.

@DependencyGraph(AppScope::class)
interface AppGraph {
  @SingleIn(AppScope::class)
  @Provides
  fun provideHttpClient(): HttpClient = HttpClient()
}

If a provider qualified, simply annotate the callable declaration with that qualifier.

@DependencyGraph
interface AppGraph {
  @ForScope(AppScope::class)
  @Provides
  fun provideHttpClient(): HttpClient = HttpClient()
}

Providers may be defined in a companion object, allowing for better staticization and slightly more efficient generated code.

interface NetworkProviders {
  companion object {
    @Provides
    fun provideHttpClient(): HttpClient = HttpClient()
  }
}

Providers may be private, though note that they will not be visible to downstream compilations in other modules at the moment. Subscribe to this issue for updates.

@DependencyGraph
interface AppGraph {
  @Provides
  private fun provideHttpClient(): HttpClient = HttpClient()
}

To nudge or enforce private providers, you can control their severity via configurable option in the Metro Gradle DSL.

metro {
  publicProviderSeverity.set(NONE|WARN|ERROR)
}

DependencyGraph.Factory

If a parameter on a dependency graph factory is annotated with this, that instance is added as an instance binding to the graph.

For example:

@DependencyGraph.Factory
interface Factory {
  fun newMyGraph(
    @Provides foo: Foo,
    @Provides @Blue bar: Bar
  ): MyGraph
}

will allow clients of the factory to pass their own instances of Foo and Bar, and those instances can be injected within the graph as Foo or @Blue Bar, respectively.