Log in to GraphQL Editor
GraphQL - schema-first vs code-first

Tomek Poniatowicz


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 vs code-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 (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.

LanguageSchema-first implementationCode-first implementation
JavaScript/TypeScriptApollo serverNexus
PHP (Laravel)Lighthouselaravel-graphql
.NETGraphQL for .NETGraphQL for .NET

What would 2020 bring? Well, I can't wait to find out :)

GraphQL Evolution

Source: prisma.io/blog

Check out our other blogposts

Top tools for a junior frontend developer
Robert Matyszewski
Robert Matyszewski
Top tools for a junior frontend developer
5 min read
over 5 years ago
Open-source GraphQL framework for Spring Boot by Netflix
Tomek Poniatowicz
Tomek Poniatowicz
Open-source GraphQL framework for Spring Boot by Netflix
3 min read
over 3 years ago
GraphQL Resources - beginner tools, extensions & tutorials
Tomek Poniatowicz
Tomek Poniatowicz
GraphQL Resources - beginner tools, extensions & tutorials
2 min read
over 5 years ago

Ready for take-off?

Elevate your work with our editor that combines world-class visual graph, documentation and API console

Get Started with GraphQL Editor