Creating a new query hook

In this guide, we will walk you through the process of creating a new query hook in Blueprint using React Query.

App or Shared?

Before you start, determine whether your query hook will be used only within a single app or can be shared across multiple apps. This will help you decide where to place your hook. For example, if the hook returns data specific to a single app, it should be app-specific. Conversely, if it returns data that can be used in multiple different markets, it should be shared.

I need to create a single-app query hook

Create the hook file: Navigate to the appropriate directory within your app (e.g., apps/demo-site/src/hooks) and create a new file for your hook (e.g., useSampleQuery.ts).

Write the hook code: Implement your hook using React Query and TypeScript. If the query is to a Kraken endpoint, use one of Blueprint's custom query hooks to ensure consistency in authentication and error handling (e.g., useKrakenQuery). Here is a basic example:

import { useKrakenQuery } from '@krakentech/blueprint-api';
import { graphql } from '@core/gql-tada';

const sampleQuery = graphql(`
    query Sample($id: String!) {
        sample(id: $id) {
            title
            description
        }
    }
`);

interface UseSampleQueryArgs {
    id: string;
}

export const useSampleQuery = ({ id }: UseSampleQueryArgs) =>
    useKrakenQuery({
        query: sampleQuery,
        variables: { id },
        queryKey: ['sampleData', id],
    });

Use the hook: Import and use your new hook within your app as needed.

import { useSampleQuery } from '../hooks/useSampleQuery';

const SampleComponent = ({ id }: { id: string }) => {
    const { data, error, isLoading } = useSampleQuery({ id });

    if (isLoading) return <div>Loading...</div>;
    if (error) return <div>Error loading data</div>;

    return (
        <div>
            <h1>{data.sample.title}</h1>
            <p>{data.sample.description}</p>
        </div>
    );
};

export default SampleComponent;

I need a shared package query hook

Create the hook file: Navigate to the appropriate directory within the packages directory (e.g., packages/utils/src/hooks) and create a new file for your hook (e.g., useSharedSampleQuery.ts).

Write the hook code: Implement your hook using React Query and TypeScript. Here is a basic example:

import { useKrakenQuery } from '@krakentech/blueprint-api';
import { graphql } from '@core/gql-tada';

const sampleQuery = graphql(`
    query Sample($id: String!) {
        sample(id: $id) {
            title
            description
        }
    }
`);

interface UseSharedSampleQueryArgs {
    id: string;
}

export const useSharedSampleQuery = ({ id }: UseSharedSampleQueryArgs) =>
    useKrakenQuery({
        query: sampleQuery,
        variables: { id },
        queryKey: ['sharedSampleData', id],
    });

Export the hook: Ensure your hook is exported from the package's entry point (e.g., packages/utils/src/index.ts).
```
export { useSharedSampleQuery } from './hooks/useSharedSampleQuery';
```
Build the package: Run npm build:packages at the root to build the package and ensure your changes are implemented.

Use the hook: Import and use your new shared hook within any app as needed.

import { useSharedSampleQuery } from '@krakentech/blueprint-utils';

const SampleComponent = ({ id }: { id: string }) => {
    const { data, error, isLoading } = useSharedSampleQuery({ id });

    if (isLoading) return <div>Loading...</div>;
    if (error) return <div>Error loading data</div>;

    return (
        <div>
            <h1>{data.sample.title}</h1>
            <p>{data.sample.description}</p>
        </div>
    );
};

export default SampleComponent;

Creating a new query hook

App or Shared?​

I need to create a single-app query hook​

I need a shared package query hook​

App or Shared?

I need to create a single-app query hook

I need a shared package query hook