GraphQL - schema-first vs code-first

GraphQL started back in 2012 at Facebook HQ. Before being publicly released in 2015 it was used internally as a cure to the underperformance observed in mobile apps on slower networks. GraphQL is a query language for APIs, its main advantage is allowing clients to define exactly what type of data is required. The centerpiece of any GraphQL project is its schema.

GraphQL schema is a set of rules describing the functionality available to the client, including specification of operations (queries and mutations) that can be executed to execute against your data graph.

If you ever decide to build a GraphQL service at some point you would need to chose which approach you want to affiliate with more:

Schema-first - prioritizing process of designing the schema,
Code-first (resolver-first) - approach prioritizing code over schema, where the GraphQL schema is generated programmatically.

In either case, we will end up with a fully functional GraphQL service, but this choice will influence your project in terms of the amount of work you will need to put to achieve certain things like scaling your project etc.

Schema-first

Schema-first is an approach that puts schema as your source of truth and forces your code to follow the definitions stored in your schema. In general, prioritizing thinking about the schema. If schema design falls short, you might end up with an API that's ignoring your business needs and needs of your end-users.

Some of the pros:

it should most of the times results in a better-designed API,
it's more abstract and less dependent by following the dependency inversion principle (DIP),
Schema-first approach reduces development time by allowing frontend and backend teams simultaneously (schema data is easily mockable i.e. with graphql-editor mock backend feature 🚀),

Some of the cons/difficulties:

the schema definition must be constantly synced with the resolvers, otherwise might cause serious problems,
might lead to code redundancy as SDL definitions are not so easily reusable,
difficulty in combining distributed schemas into a single schema (require using 3rd party tools like graphql-editor or graphql-tools)

Code-first

Code-first (often called resolver-first) is a process where the schema is defined and implemented programmatically. The design process begins with coding the resolvers and the SDL version of the GraphQL schema is a generated artifact (created with a script, not manually).

Some of the pros:

can work as a single source of truth as it keeps stored both the schema definitions as well as resolvers,
code-first can easily overcome difficulties met in schema-first approach, without the usage of a vast amount of tools,
better manageable if you expect your schema to grow in complexity or size,

Some of the cons/difficulties:

having both the definitions and resolves might be less readable,
your API design is easier influenced by implementation rather than business needs,
backward-incompatible changes can slip in more easily compared to schema's first approach.

The evolution

When GraphQL was publicly released in the 2015 ecosystem we know haven't existed (quite obvious) and the only things that we could lean on were the official GraphQL specification and graphql-js (the reference implementation in JavaScript) until 2016 when graphql-tools repo was founded which firstly promoted schema-first approach by separating two layers of working with schema:

the schema definition - writing GraphQL schema definition using Schema Definition Language (SDL),
the schema implementation - writing required resolvers.

After that, the schema-first become default approach but seeing its limitations people started looking for some workarounds which led to first code-first frameworks being released. The Code-first approach is becoming so popular that almost every GraphQL implementation now has its code-first alternative, or even focusing on only the code-first path.

Language	Schema-first implementation	Code-first implementation
JavaScript/TypeScript	Apollo server	Nexus
PHP (Laravel)	Lighthouse	laravel-graphql
PHP (WP)	x	WPGraphQL
Python	Ariadne	Graphene
.NET	GraphQL for .NET	GraphQL for .NET
Rust	x	Juniper