Step 1 - Preparing the folders and files

1. In your store repository, go to the src folder and create the graphql subfolder. You can do this by running the following command in your terminal:
   
   

   _10

   mkdir graphql

   
   
2. Inside the new graphql folder, create the vtex subfolder.
   
   

   _10

   mkdir vtex

   
   
3. In the vtex folder, create resolvers and typeDefs subfolders.
   
   

   _10

   mkdir resolvers typeDefs

   
   

   The src/graphql/vtex/resolvers and src/graphql/vtex/typeDefs paths are mandatory when adding VTEX API Extensions, but you can organize the files inside those directories as you wish.

4. Create a index.ts file inside the resolvers folder.
   Once you have created the essentials folders, you will have a folder structure for the VTEX API Schema extensions in the src/graphql/vtex folder similiar to the the following:
   
   

   _11

   starter.store/

   _11

   └─ src/

   _11

   └─ graphql/

   _11

   └─ vtex/

   _11

   ├─ resolvers/

   _11

   └─ index.ts

   _11

   └─ <resolverName>.ts

   _11

   └─ …

   _11

   ├─ typeDefs/

   _11

   └─<typeName>.graphql

   _11

   └─ …

   
   

   Note that in the code example above, the type definitions and resolvers files were created at <resolverName>.ts and <typeName>.graphql.

Step 2 - Creating type definitions (typeDefs)Your new type definitions set the data structure for your new fields, extended from the existing FastStore API GraphQL queries and types

1. Create a new <typeName>.graphql file inside the vtex/typeDefs folder. For example, let's extends the StoreProduct type from FastStore API, so the name of the file is product.graphql.

   The way that it will be organized inside this folder is flexible, it's possible to create multiple typeDefs files or group them all together in just one file. During the build process and when running the local server file, all .graphql files under this directory will be considered.

2. To extend the StoreProduct, let's add a customData field in the product.graphql and it should return a string value. This field can store custom information related to a product in your store. For example, you might use this field to store additional product details that are not present in the native FastStore API schema.
   graphql/vtex/typeDefs/product.graphql

   
   

   _10

   extend type StoreProduct {

   _10

   """

   _10

   Custom data extending StoreProduct

   _10

   """

   _10

   customData: String!

   _10

   }

   
   

   The typeDefs files must have .graphql extension. Also, the index.ts is not needed for typeDefs, only for resolvers.

   Now, refer to the next step to create the resolvers to provide the actual data to the customData field.

Step 3 - Creating resolvers

1. Create a new <resolverName>.ts file inside the vtex/resolvers folder. Let's continue the StoreProduct type example, so the name of the file is product.ts.

   The way that it will be organized inside this folder is flexible, it's possible to create multiple resolvers files or group them all together in just one file.

2. Define the resolver in the product.ts file. This resolver specifies how to fetch the data for the customData field based on the root object.
   graphql/vtex/resolvers/product.ts

   
   

   _11

   import type { StoreProductRoot } from '@faststore/core/api'

   _11

   _11

   const productResolver = {

   _11

   StoreProduct: {

   _11

   customData: (root: StoreProductRoot) => {

   _11

   return 'My item id: ' + root.itemId

   _11

   },

   _11

   },

   _11

   }

   _11

   _11

   export default productResolver

   
   
   Note that you can leverage the use of TypeScript by typing the root param as StoreProductRoot:
   
3. Open the index.ts file inside the vtex/resolvers folder and import the resolver, StoreProductResolver, you created in the previous step.
4. Export a new resolvers object that includes the imported resolver(s).
   graphql/vtex/resolvers/index.ts

   
   

   _10

   import { default as StoreProductResolver } from './product'

   _10

   _10

   const resolvers = {

   _10

   ...StoreProductResolver,

   _10

   }

   _10

   _10

   export default resolvers

   
   
   Once you have defined these files in the vtex folder, the new fields are already available for use. To consume the fields, refer to the Consuming FastStore API extension with custom components guide.

   If the changes you made are still not available, refer to the troubleshooting section GraphQL changes not visible during development.

Step 1 - Preparing the folders and files

For third-party API schemas, you only need to add the thirdParty folder within the 'src/graphql' directory.

1. In your store repository, go to the src folder and create the graphql subfolder. You can do this by running the following command in your terminal:
   
   

   _10

   mkdir graphql

   
   
2. Inside the new graphql folder, create the thirdParty subfolder.
   
   

   _10

   mkdir thirdParty

   
   
3. In thirdParty, create resolvers and typeDefs subfolders.
   
   

   _10

   mkdir resolvers typeDefs

   
   

   The src/graphql/vtex/resolvers and src/graphql/vtex/typeDefs path is mandatory, but you can organize the files inside those directory as you wish.

4. Create a index.ts file inside the resolvers folder.
   Once you have created the essentials folders, you will have a folder structure similiar to the the following:
   
   

   _11

   starter.store/

   _11

   └── src/

   _11

   └── graphql/

   _11

   ├── thirdParty/

   _11

   │ ├── resolvers/

   _11

   │ └── index.ts

   _11

   │ └── <resolverName>.ts

   _11

   │ └── …

   _11

   │ ├── typeDefs/

   _11

   │ └── <typeName>.graphql

   _11

   │ └── …

   
   

   This directory structure distinguishes between data originating from VTEX and data from third-party APIs.

Step 2 - Creating type definitions and resolvers

1. Create a new <typeName>.graphql inside the thirdParty folder. As we are creating new queries, the name of the file that defines the type definitions can be extra.graphql.
2. Create a new <resolver>.ts file inside the graphql/thirdParty/resolvers folder.

Step 3 - Creating query or mutation schemas

1. In the extra.graphql file, add the following:
   graphql/thirdParty/typeDefs/extra.graphql

   
   

   _12

   _12

   type ExtraData {

   _12

   """

   _12

   Data customizing ExtraData

   _12

   """

   _12

   data: String!

   _12

   }

   _12

   _12

   type Query {

   _12

   extraData: ExtraData

   _12

   namedExtraData(name: String!): ExtraData

   _12

   }

   
   
2. In the <resolver>.ts file, let's continue the example, so the file name can be extra.ts. This file defines the resolvers that handle the logic for the defined queries or mutations.
   graphql/thirdParty/resolvers/extra.ts

   
   

   _17

   _17

   const extraDataResolver = {

   _17

   Query: {

   _17

   extraData: () => {

   _17

   return {

   _17

   data: 'Extra data',

   _17

   }

   _17

   },

   _17

   namedExtraData: (_, { name }) => {

   _17

   return {

   _17

   data: `Named extra data: ${name}`,

   _17

   }

   _17

   },

   _17

   },

   _17

   }

   _17

   _17

   export default extraDataResolver

   
   
3. In the graphql/thirdParty/resolvers folder, create an index.ts file to combine all the resolvers into a single object.
   graphql/thirdParty/resolvers/index.ts

   
   

   _10

   _10

   import { default as StoreExtraResolver } from './extra'

   _10

   _10

   const resolvers = {

   _10

   ...StoreExtraResolver,

   _10

   }

   _10

   _10

   export default resolvers

   
   
4. With the schema and resolvers in place, you can query the data using GraphQL queries. Here's an example query to access the extra data:
   
   

   _10

   query {

   _10

   extraData {

   _10

   data

   _10

   }

   _10

   namedExtraData(name: "Hello") {

   _10

   data

   _10

   }

   _10

   }

   
   
   Once you have defined these files in the thirdParty folder, you can query the data you defined.

   If the changes you made are still not available, refer to the troubleshooting section GraphQL changes not visible during development.