WunderGraph Cosmo: a open source alternative to Apollo Federation, GraphOS, Studio, etc...
Tags: graphql, opensource, webdev, javascript
Published: 2023-09-13 15:20:09


It's launch day again! 🚀

Yesterday, we've launched [Open Federation](https://open-federation.org), an open specification for building federated GraphQL APIs.

Today, we're launching WunderGraph Cosmo, an open source alternative to Apollo Federation, GraphOS, Studio, etc...

Cosmo is a complete solution for building federated GraphQL APIs built on top of Open Federation and therefore compatible with Apollo Federation v1 and v2 Subgraphs.

It's a complete solution including Schema Registry, Schema Checks, CLI, Studio, Metrics, Tracing and Telemetry.

Cosmo is Apache 2.0 licensed, you can use it as a [Managed Service](https://cosmo.wundergraph.com) or self-host it.
The source code can be found on [GitHub](https://github.com/wundergraph/cosmo).

## Why Cosmo?

For more than five years, we've been involved in the GraphQL ecosystem, building tools and services around GraphQL, like [graphql-go-tools (https://github.com/wundergraph/graphql-go-tools),
a library to build GraphQL Gateways in Go.

I was always fascinated by the idea of using GraphQL to compose multiple APIs into a single unified API,
so I started building an open source GraphQL Engine / Gateway as part of graphql-go-tools.

Initially, the engine supported GraphQL & REST APIs.

When Apollo announced Federation and the Subgraph Directives, I was immediately hooked and extended the GraphQL Data Source to understand [the Subgraph Directives](https://github.com/wundergraph/graphql-go-tools/pull/231).

However, after the initial implementation was done,
my focus shifted to other projects and didn't get back to it for a while.

Fast forward to 2023, all of this should suddenly change. We suddenly got more and more requests from companies that were looking for open source tooling to build federated GraphQL APIs.

One thing led to another and we've decided to "pick up" our old GraphQL Engine and build a complete solution around it: Cosmo!

We've decided to follow a similar path as Supabase and build a fully open source alternative to an existing solution.

The benefits of this approach are obvious. No vendor lock-in, more transparency, and you can self-host the whole solution in case you are under strict compliance requirements.

Furthermore, I believe we can overall build a better solution when the codebase is open source and the community can contribute.

## Cosmo Overview

At a high level, Cosmo is composed of four main component, the Schema Registry / Control Plane,
the Studio / UI, the Router / Data Plane,
and the CLI to manage your graphs.

![Cosmo OverView](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/h1cajljy9ule32db8wyt.png)


## Cosmo Architecture

Cosmo builds on top of Open Telemetry (OTEL) for tracing as well as Prometheus for metrics.
Cosmo comes with its own Router which is written in Go.

The Router can easily be [extended and customized](https://cosmo docs.wundergraph.com/router/customizability).


![Cosmo Architecture](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/zlrsmgjz65t3fry9usg5.png)


In the next two days, we will go into more detail about Analytics, Tracing, and Metrics as well as the Router.

## Cosmo Studio

Cosmo Studio is a web-based UI to manage your graphs.
It's built with NextJS and TailwindCSS.


![Cosmo Studio](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/bue6iqsfwc8ycq66wub0.png)


Cosmo Studio gives you a quick overview of your graphs and their health status, it allows you to inspect the schemas and types of all your graphs, you can see the history and changelog of your graphs, and you can view analytics, metrics and traces of your GraphQL APIs.

## Composing federated GraphQL APIs with Schema Checks

At the heart of Cosmo is the Schema Registry.
The Schema Registry is responsible for storing the schemas of your federated GraphQL APIs.

Whenever you intend to deploy a new version of a subgraph, Cosmo will allow you to check if all subgraphs are still compatible with each other.

There's a complex set of rules that one has to implement to handle all the different cases.

We've invested a couple of months to implement a robust and reliable solution to solve this problem.
Thanks to all the companies that have supported us during this time, we've got enough subgraph Schemas to test our implementation.

Once we're confident that we've implemented all the rules correctly, we will contribute the rules to [Open Federation](https://open-federation.org) so that other implementations can benefit from it as well.

## Cosmo CLI

Cosmo comes with a CLI to manage your graphs.
It's a pretty simple CLI that allows you to manage your graphs and run schema checks.

1. create a new graph

```bash
npx wgc subgraph create products --label team=A --routing-url http://localhost:4001/graphql
```

2. run a schema check

```bash
npx wgc subgraph check products --schema ./schemas/new_schema.graphql
```

3. update a graph

```bash
npx wgc subgraph update products -r http://new-domain.com/graphql
```

## Using AI to fix your GraphQL Schema

When we were experimenting with this tooling, we've noticed that sometimes the schema checks would fail for very obvious reasons,
e.g. a field was removed from a type but is still being used as a key in a `@key` directive.
We thought to ourselves, why not use AI to use the schema check results to fix the schema automatically?

So, we've added a "fix" command to the CLI to do exactly that.
Why ask for changes when you can just fix them automatically?

```bash
npx wgc subgraph fix products --schema ../demo/subgraphs/products/products.graphql --out-schema ../demo/subgraphs/products/products-fix.graphql
```

## Migrating from Apollo GraphOS to Cosmo

So, how can you try out Cosmo and migrate from Apollo GraphOS to Cosmo?
It's pretty simple, actually!

1. Log in to [Cosmo Studio](https://cosmo.wundergraph.com)
2. Click the Migrate Button and follow the instructions
2. Replace Apollo Gateway / Router with Cosmo Router
3. done!


![Apollo GraphOS Migration](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/fofbeb04u1xgx19qyf7w.png)


More details can be found in the [Migration Guide](https://cosmo-docs.wundergraph.com/studio/migrate-from-apollo).

## Say hello to CosmoNaut

What's a great tool without a mascot?
Say hello to "CosmoNaut", traveling the universe to discover new graphs and connect all of them.


![CosmoNaut](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5fc3i0pc2b6f6iozy4zz.png)


## Meet us at GraphQL Conf next week

As a reminder, we will be at GraphQL Conf next week in San Francisco.

If you're interested in Open Federation or Cosmo, come and say hi!

In addition, I will be giving a [talk about "Dataloader 3.0"](https://graphql.org/conf/schedule/09bc04c42310bfe14024455bce46d781),
which is a recapt of five years of building GraphQL API Gateways.
I will discuss the evolution of "data loading" in GraphQL and how it can be further improved in the future.

## Conclusion

Alright, that's it for today.
Now have a look at the [GitHub Repository](https://github.com/wundergraph/cosmo) and give it a ⭐️.

If you want to learn more about Cosmo, check out the [documentation](https://cosmo-docs.wundergraph.com/).