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 the Foundation app or can be shared (e.g. in a package). This will help you decide where to place your hook. For example, if the hook returns data specific to one client or configuration, it should live in the app. Conversely, if it returns data that can be reused across the app or by other features, 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/foundation/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/client';
import { graphql } from '@foundation/gql-tada';

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

interface UseSampleQueryArgs {
    id: string;
}

export const useSampleQuery = ({ id }: UseSampleQueryArgs) =>
    useKrakenQuery({
        document: 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/client';
import { graphql } from 'gql.tada';

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

interface UseSharedSampleQueryArgs {
    id: string;
}

export const useSharedSampleQuery = ({ id }: UseSharedSampleQueryArgs) =>
    useKrakenQuery({
        document: 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/client';

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;

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