The graphql builder handles the GraphQL app schema and serves as an interface between frontend applications and backend services. This guide provides a comprehensive overview of how to use this builder effectively. For more information, see Developing a GraphQL API in service apps and the official GraphQL documentation.

The graphql builder is used only when developing an app's GraphQL API. You don't need this builder to consume GraphQL APIs in IO apps.

The graphql builder is available in the following versions:

Builder version	Mandatory @auth directive*	Status
1.x	No	Unavailable for new apps and new major versions of existing apps. Available for linking apps and publishing new minor and patch versions of existing apps until January 7, 2026.
2.x	Yes	Active

* The @auth directive adds an authorization step to GraphQL queries and mutations. For more details, see GraphQL authorization in IO apps.

Apps using deprecated builder versions can still run on the VTEX platform, but developers can't build or create new app versions using these builder versions.

The graphql builder uses a graphql folder in the app's root folder. This folder contains .graphql files with the schema definitions. Developers can structure the whole schema in a single file or split it into multiple files and subfolders.

We recommend you to:

• Define only the endpoints (queries, mutations, and subscriptions) in schema.graphql.
• Handle directives separately in directives.graphql.
• Define additional types in separate files inside the types subfolder.

To develop an app using the graphql builder, follow the steps below:

1. Start with a template: Download an app template such as graphql-example or create a new project using the vtex init CLI command and select the graphql-example option.
2. Add the schema files: Add the .graphql files with the schema definitions, including the endpoints (queries, mutations, and subscriptions), directives, and other custom types.
3. Add the API implementation logic: Add the code that implements and instantiates the resolver functions.
   1. Create the resolvers: Create the resolver functions that will run when your GraphQL endpoints are called. The functions must have the same names as the endpoints defined in the schema. If you're developing a Node service, add the TypeScript code (.ts files) in the node/resolvers folder.
   2. Instantiate the resolvers: Add the code to instantiate the resolvers. If you're developing a Node service, in the node/index.ts file, within the Service class, you should add a graphql field that includes the resolvers for each implemented endpoint and the directives.
4. Testing: Link the app to a development workspace for testing. Test the endpoints with the GraphQL IDE.

For a more detailed tutorial on implementing an app with this builder, see Developing a GraphQL API in service apps.

Below are some app examples that use the graphql builder:

• b2b-organizations-graphql
• b2b-quotes-graphql
• my-account
• session-client