​
Introduction

gRPC plugins are extensions that run as separate processes locally alongside the Cosmo Router and communicate over Google’s Remote Procedure Call (gRPC) protocol. Unlike gRPC services that run remotely over the network, plugins provide the simplest deployment model with the highest performance for GraphQL Federation. The Cosmo cli (wgc) provides you with a set of tools to create and build gRPC plugins. Together with the built-in testing framework, gRPC plugins are purpose-built to leverage LLMs to generate adapter code between your GraphQL Schema and the underlying data source.

In addition, the Cosmo Router manages the lifecycle of plugins, including hot-reloading plugins without any service interruption. There’s no need to deploy “Subgraph” services just to bring an existing API into your Supergraph.

For an overview of gRPC concepts shared between plugins and services, see our gRPC Concepts documentation.

​
Workflow

1

Define a Subgraph Schema

Define a regular Subgraph Schema like you’re used to

2

Generate a proto definition

Use wgc to generate a proto definition for your plugin

3

Implement the plugin

Implement the plugin in Go using the generated interfaces

4

Connect to your Router

Hook up the plugin to your Router configuration

gRPC plugins are currently in beta. The API may change in future releases.

​
What Makes gRPC Plugins Unique

gRPC plugins are local extensions that run as separate processes managed by the Cosmo Router. These plugins:

​
Demo and Example

If you prefer to explore new solutions by looking at code and running it locally, take a look at our Cosmo Plugin Demo repository.

​
What are gRPC Plugins?

gRPC plugins are extensions that run as separate processes and communicate with the Cosmo Router over Google’s Remote Procedure Call (gRPC) protocol.

Running as separate processes provides critical fault isolation - if a plugin crashes or encounters a fatal error, it won’t bring down your router process.

These plugins implement GraphQL resolvers that can access any data source or service, all while communicating with the Router through a high-performance gRPC interface.

The plugin architecture is built on HashiCorp’s battle-tested go-plugin framework, which powers production systems like Vault and Terraform with millions of deployments worldwide. This provides enterprise-grade reliability, secure process isolation, and proven stability for your GraphQL infrastructure.

​
Motivation

A lot of companies see the value of GraphQL Federation but are hesitant to adopt it because they have existing systems that are incompatible, like legacy systems, REST APIs, SOAP, etc…

gRPC plugins solve this problem by making it very easy to generate adapters between your Supergraph and existing systems. The plugin system is designed with tools like Cursor, Windsurf, and Copilot in mind. Define a Subgraph Schema, provide an OpenAPI document, a SOAP WSDL, or even just some curl commands, and your LLM will be able to generate adapter code and tests in just a few minutes.

Thanks to the strongly-typed proto definition and the built-in testing framework, LLM coding assistants can quickly iterate on the generated code and ensure it’s correct.

Our goal is to allow you to one-shot generate an adapter for an existing system with a single prompt.

Simplify GraphQL Implementation

While everyone understands the value of “one schema, one query,” building and maintaining production-grade subgraphs across diverse environments remains challenging. Spec support, runtime performance, and type safety depend on your subgraph framework quality.

Design with GraphQL, Implement with gRPC

Our approach combines GraphQL’s schema-first flexibility with gRPC’s performance and type safety. Using the same plugin system that powers HashiCorp Vault and Terraform, you can develop subgraphs in any language and run them directly in the Cosmo Router.

Proto-Based Code Generation

The strict typing and automatic code generation from Protocol Buffers (proto) definitions provides an immense productivity boost, especially in the era of generative AI. The generated proto-based gRPC code creates a strongly-typed foundation that AI tools can more effectively understand, extend, and modify, reducing development time and errors while ensuring consistent API implementation.

Strongly-Typed Subgraphs

It’s impossible to know if a Subgraph Framework properly implemented the GraphQL Federation contract. With gRPC plugins, there’s no way to get around the proto definition. If the implementation compiles against the proto definition, you know it’s correct. This eliminates a whole class of issues around Subgraph Implementation Quality.

Apollo Federation Subgraph Interoperability

gRPC plugins are 100% compatible with existing Apollo Federation Subgraph Implementations. This means you can use gRPC plugins alongside existing Apollo Federation Subgraphs.

No N+1 Problems

Declarative approaches like Apollo Connectors suffer from N+1 problems and make it impossible to batch origin requests. gRPC plugins leverage Cosmo Router’s DataLoader capabilities which batches requests by default.

No Subgraph Framework Lag

When new features are added to the Apollo Federation Subgraph Specification, it can take months for all Subgraph Implementations to catch up. gRPC plugins handle all Federation related logic within the Router, only exposing rpc methods for queries, mutations, and entity lookups. As a result, you can always immediately take advantage of the latest features in any language that supports gRPC.

Breaking free from Apollo

Apollo being the maintainer of the majority of Subgraph Framework implementations limits the speed of innovation. With gRPC plugins, we’re able to break free from Apollo’s constraints and innovate at a much faster pace.

​
Benefits Over Traditional Subgraphs

When compared to traditional standalone subgraphs, gRPC plugins offer substantial technical advantages:

Simplified Architecture

Maintain fewer components with unified deployment and monitoring. You can run multiple plugins on the same Router.

Performance

Achieve significantly lower latency with direct gRPC-based communication. The network and GraphQL framework overhead is eliminated.

Enhanced Developer Experience

Work with consistent tooling and deployment patterns across all Subgraphs. If your team knows how to work with gRPC, they know how to build Subgraphs.

Seamless Integration

Connect to legacy systems, databases, and APIs without intermediate GraphQL services. The plugin can be written in any language that supports gRPC.

This architecture gives you a unified development experience with consistent tooling across all your subgraphs while enabling seamless integration with your existing infrastructure.

​
gRPC Plugin Architecture

The gRPC plugin architecture works by:

  1. Plugin Registration: Plugins are registered with the Cosmo Router at startup
  2. Schema Integration: The plugin’s schema is integrated into the federated graph
  3. Request Handling: When the Router receives a GraphQL request, it routes relevant parts to the appropriate plugins
  4. Inter-Process Communication: Plugins run in separate processes and communicate with the router via gRPC
  5. Response Assembly: The Router assembles the complete response from all plugins and regular subgraphs

​
Limitations

While powerful, gRPC plugins have some considerations:

  • Language Support: Currently, only Go is supported for plugin development
  • Deployment Coupling: Plugins must be deployed with the Router rather than independently

We’re working on adding support for more languages and making the deployment workflow much simpler.

​
Bootstrapping a gRPC Plugin

Cosmo provides a set of CLI tools to simplify the process of creating, building, and testing gRPC plugins. These tools handle much of the boilerplate code generation and build process for you.

​
Prerequisites

Before using the plugin CLI tools, make sure you have:

  • WunderGraph Cosmo CLI installed
  • The Go compiler, protobuf compiler, and protoc plugins are installed automatically by the CLI. However, you can install them manually if you prefer.

​
Creating and Building Plugins

The Cosmo CLI provides the following commands for working with plugins:

For detailed documentation on each command, visit the CLI Plugin Commands section.

​
Typical Workflow

We will ask you to install the dependencies for you to compile and test the plugin. However, for the best experience, we recommend you install the dependencies manually and use a IDE with Go support. Please refer to the CLI Plugin Commands documentation for more details.

Here is a simplified workflow for creating a gRPC plugin with a fully working router setup:

# 1️⃣ Initialize a full router project with a plugin
wgc router plugin init hello-world

# 2️⃣ Go to the project directory "cosmo" (default)
# Build, compose and start the router. Navigate to http://localhost:3010
make

# 3️⃣ Customize the schema and implementation to your needs
# Edit `./plugins/hello-world/src/schema.graphql`

# 4️⃣ Generate the Go code for your plugin to implement the resolvers
cd plugins/hello-world && make generate

# 5️⃣ Now you can implement your gRPC resolvers in `./plugins/hello-world/src/main.go`

# ⭐ Regenerate the code, build the plugin and serve the latest config.
# Navigate to http://localhost:3010 again to query your supergraph
make

Every plugin comes with a Makefile that provides a set of commands to build, test, and run the plugin.

​
Plugin Directory Structure

When you initialize a plugin using wgc router grpc-plugin init, it creates a complete router project with a hello world plugin.

For more details on the directory structure and build process, see the wgc router grpc-plugin init documentation.

​
Debugging Plugins

Please refer to the Debugging Plugins documentation for more details.

​
Deployment Considerations

When deploying gRPC plugins with your Cosmo Router, keep these important considerations in mind:

​
Platform Compatibility

Plugins must be compiled for the same target platform as your router. This means:

  • If your router runs on Linux AMD64, your plugins must be built for Linux AMD64
  • If deploying to multiple architectures, plugins must be cross-compiled for each target platform

​
Docker Integration

For containerized deployments:

  1. Plugins must be embedded into the same Docker image as the Router
  2. The Router’s configuration file must correctly reference the plugins path within the container

Example Dockerfile:

This is an example Dockerfile that embeds the plugins into the router image. You can use volume mounts to avoid building specific docker images for each plugin.

FROM ghcr.io/wundergraph/cosmo/router:latest

# Copy the router configuration
COPY config.yaml /app/config.yaml
COPY config.json /app/config.json

# Copy the plugins to the container
COPY ./plugins /app/plugins

# Set the working directory
WORKDIR /app

# The entrypoint is already set in the base image

​
Future Enhancements

We’re actively working on enhancing plugin deployment with:

  • Cosmo Cloud Plugin Registry: Native integration with Cosmo Cloud allowing you to push plugins directly to the platform without the need to re-deploy the Router

These capabilities will further simplify the management and deployment of plugins in production environments.

​
Conclusion

gRPC plugins for the Cosmo Router provide a powerful way to implement high-performance subgraphs that communicate with the Router via a secure cross-process architecture. By leveraging the battle-tested HashiCorp go-plugin framework while maintaining clean separation of concerns, they offer the best of both worlds for many use cases.

For complex systems, consider a hybrid approach: use gRPC plugins for performance-critical paths and traditional subgraphs for areas that require independent scaling or deployment.