Custom Queries

Introduction

Sometimes you need to fetch data from Magento that the default methods don't cover. You have two ways to do this:

• Add a custom API method (recommended) - write your own middleware method with a GraphQL query. You get full editor support: syntax highlighting, schema-aware autocompletion, and type safety.
• Use the customQuery feature - pass an inline GraphQL query string to an existing method to extend its default query.

This guide covers both, and shows how to set up your editor so writing GraphQL feels like writing GraphQL - not editing a plain string.

Recommended: add a custom API method

For most cases, a custom API method is the better developer experience. Because the query lives in a regular TypeScript file, you can tag it with gql (from the graphql-tag package, already available in the middleware) and your editor treats it as a real GraphQL document.

import { type Context } from '@vsf-enterprise/magento-api';
import gql from 'graphql-tag';

// The `/* GraphQL */` comment + the `gql` tag give you syntax highlighting and,
// with a GraphQL editor extension installed, autocompletion against the Magento schema.
export const storeConfigQuery = /* GraphQL */ gql`
  query storeConfig {
    storeConfig {
      store_code
      store_name
      base_currency_code
    }
  }
`;

interface StoreConfigResponse {
  storeConfig: {
    base_currency_code: string;
    store_code: string;
    store_name: string;
  };
}

export async function getStoreConfig(context: Context): Promise<StoreConfigResponse> {
  const { data } = await context.client.query<StoreConfigResponse>({
    fetchPolicy: 'no-cache',
    query: storeConfigQuery,
  });

  return data;
}

The method is automatically exposed on the SDK with full type inference, so the frontend gets a typed response for free.

Custom queries

If you only need to tweak the query of an existing method, the customQuery feature lets you do that without writing a new method.

Creating a custom query requires a few steps:

• add a custom query to the integration config file,
• (optional) overwrite the default response interface,
• use the custom query in the method.

Custom queries in the middleware config

To use custom queries, add them to the customQueries object in the integration config file located at apps/storefront-middleware/integrations/magento/config.ts.

The #graphql comment at the start of the template string is what gives you syntax highlighting here - the query is passed to the method as a plain string, so don't wrap it with the gql tag.

In the example below, we add a custom query called customer-custom-query:

export const config = {
  location: '@vsf-enterprise/magento-api/server',
  configuration: {
    // ...
  },
  customQueries: {
    'customer-custom-query': ({ query, variables, metadata }) => ({
      variables,
      query: `#graphql
        query customer {
          customer {
            ${metadata.fields}
          }
        }
      `,
    }),
  },
};

Using custom queries

To use a custom query, pass the customQuery parameter to the method. It's an object that contains the name of the custom query and the variables passed to it.

In our example, we fetch a basic user profile and use the customQuery parameter to leverage the custom GraphQL query from the previous step.

import { sdk } from '~/sdk.config.ts';

type CustomerCustomQueryResponse = {
  customer: {
    email: string;
    firstname: string;
    lastname: string;
  };
};

const customQuery = {
  customer: 'customer-custom-query',
  metadata: {
    fields: 'email firstname lastname',
  },
};

// We assume that the token was already fetched and stored in the `token` variable.
const result = await sdk.magento.customer(customQuery, {
  customHeaders: { Authorization: `Bearer ${token}` },
});

Editor setup: syntax highlighting and autocompletion

Out of the box, a GraphQL query embedded in a TypeScript file is just a string - no colors, no validation, no autocompletion. Two small things fix that.

1. Mark the query as GraphQL

Editors recognize GraphQL inside a template literal in two ways:

• a gql tagged template (or a /* GraphQL */ comment before the literal) - use this in custom API methods,
• a leading #graphql comment inside the string - use this for customQuery strings, which can't be tagged.

Both are shown in the examples above.

2. Install a GraphQL editor extension

Highlighting (and, with a schema, autocompletion) is provided by an editor extension, not by Alokai. For VS Code and Cursor, install the official GraphQL extension by The GraphQL Foundation.

To unlock schema-aware autocompletion and validation, point the extension at your Magento schema with a graphql.config file at your project root:

schema: ${MAGENTO_GRAPHQL_URL}
documents:
  - 'apps/storefront-middleware/**/*.ts'