Using a gRPC client in Play

Akka gRPC has special support to allow for seamless injection of generated clients in Play. To enable this, you need first to enable the gRPC plugin as described in the client docs and then add a source generator in build.sbt:

import play.grpc.gen.scaladsl.PlayScalaClientCodeGenerator
akkaGrpcExtraGenerators += PlayScalaClientCodeGenerator
libraryDependencies += "" %% "play-grpc-runtime" % "0.9.1"
import play.grpc.gen.javadsl.PlayJavaClientCodeGenerator
akkaGrpcExtraGenerators += PlayJavaClientCodeGenerator
libraryDependencies += "" %% "play-grpc-runtime" % "0.9.1"

This will generate a Play module that provides all generated clients for injection. The module must be enabled by adding it to the enabled modules in the application.conf.

You can then put the following helloworld.proto file in app/protobuf:

syntax = "proto3";

option java_multiple_files = true;
option java_package = "example.myapp.helloworld.grpc";
option java_outer_classname = "HelloWorldProto";

package helloworld;

service GreeterService {
    rpc SayHello (HelloRequest) returns (HelloReply) {}

message HelloRequest {
    string name = 1;

message HelloReply {
    string message = 1;

The module file is generated in example.myapp.helloworld.grpc.helloworld.AkkaGrpcClientModule by default for Scala example.myapp.helloworld.grpc.AkkaGrpcClientModule by default for Java, which corresponds to the default value of flat_package for JavaScala. You can read more about this in Services.

The exact package of the module will be based on the package the proto files are generated in, configured through the java_package option in the proto-file (if there are multiple different gRPC generated clients the module will be generated in the longest package prefix shared between the clients).

To hook it into Play, in application.conf:

// enable the client module
play.modules.enabled += example.myapp.helloworld.grpc.helloworld.AkkaGrpcClientModule
// enable the client module
play.modules.enabled += example.myapp.helloworld.grpc.AkkaGrpcClientModule

The clients are configured with entries under akka.grpc.client named after the client (gRPC package name dot ServiceName), again, in application.conf:

akka.grpc.client {
  "helloworld.GreeterService" {
    host = ""
    port = 9000
    # By default we connect over TLS
    #use-tls = false

See Client Configuration for more information on the available options. If the configuration is not present for that client and it is used by some other component, the application start will fail with an exception when injecting the client (see #271).

You can now use the client in a controller by injecting it:

package controllers

import example.myapp.helloworld.grpc.helloworld.GreeterServiceClient
import example.myapp.helloworld.grpc.helloworld.HelloRequest
import javax.inject.Inject
import javax.inject.Singleton
import play.api.mvc.AbstractController
import play.api.mvc.ControllerComponents

import scala.concurrent.ExecutionContext

class MyController @Inject() (
    implicit greeterClient: GreeterServiceClient,
    cc: ControllerComponents,
    exec: ExecutionContext,
) extends AbstractController(cc) {

  def sayHello(name: String) = Action.async {
      .map { reply =>
        Ok(s"response: ${reply.message}")

package controllers;

import example.myapp.helloworld.grpc.GreeterServiceClient;
import example.myapp.helloworld.grpc.HelloRequest;
import play.mvc.Controller;
import play.mvc.Result;

import javax.inject.Inject;
import javax.inject.Singleton;
import java.util.concurrent.CompletionStage;

public class MyController extends Controller {

  private final GreeterServiceClient greeterServiceClient;

  public MyController(GreeterServiceClient greeterServiceClient) {
    this.greeterServiceClient = greeterServiceClient;

  public CompletionStage<Result> sayHello(String name) {
    return greeterServiceClient
        .thenApply(response -> ok("response: " + response.getMessage()));
Found an error in this documentation? The source code for this page can be found here. Please feel free to edit and contribute a pull request.