@bota-apps/hooks

The generic data layer for @bota-apps apps: a configured React Query client wired to the feature error tracker, the GraphQL client context/provider, and typed query/mutation pipeline wrappers. Domain hooks stay in each app (built on these) — this package ships only the generic plumbing.

Install

pnpm add @bota-apps/hooks
# peers: @tanstack/react-query, react, graphql

Usage

Provide the clients near the app root

QueryProvider mounts the shared queryClient; GraphQLProvider puts a @bota-apps/gql-client GraphQLClient on context so the useGql* hooks and useGraphQLClient() can reach it.

import { QueryProvider, GraphQLProvider } from "@bota-apps/hooks";
import { createGraphQLClient } from "@bota-apps/gql-client";

const client = createGraphQLClient("https://api.example.com/graphql");

<QueryProvider>
  <GraphQLProvider client={client}>{children}</GraphQLProvider>
</QueryProvider>;

Typed operations with the useGql* hooks

Pass a TypedDocumentNode (e.g. from @bota-apps/gql-codegen) and the field result type is inferred. useGqlQuery unwraps the single root field for you, and gqlQueryKey derives a stable query key from the document + variables:

import { useGqlQuery, useGqlMutation } from "@bota-apps/hooks";

export function useProjects() {
  return useGqlQuery(ProjectsDocument); // UseQueryResult<Project[], Error>
}

export function useProject(id: string) {
  return useGqlQuery(ProjectDocument, { id }); // variables passed positionally
}

export function usePromoteProject() {
  return useGqlMutation(PromoteProjectDocument, {
    invalidates: [["projects"]], // shorthand for meta.invalidates
  });
}

Build a domain hook on the raw pipelines

When you need a bespoke queryFn, use the pipelines directly. They forward failures to the feature tracker and honour meta.featureId / meta.invalidates:

import { useQueryPipeline, useGraphQLClient } from "@bota-apps/hooks";

export function useProjects() {
  const client = useGraphQLClient();
  return useQueryPipeline({
    queryKey: ["projects"],
    queryFn: () => client.request(ProjectsDocument).then((r) => r.projects),
    meta: { featureId: "projects" },
  });
}

API

| Export | What | | -------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | queryClient | The shared, pre-configured QueryClient instance | | QueryProvider | Mounts queryClient via QueryClientProvider | | GraphQLContext / useGraphQLClient | React context holding the GraphQLClient; hook throws if used outside a provider | | GraphQLProvider | Puts a GraphQLClient on GraphQLContext | | useQueryPipeline / useSuspenseQueryPipeline | useQuery / useSuspenseQuery wrappers with feature-tracker error forwarding | | useMutationPipeline | useMutation wrapper honouring meta.invalidates (auto query invalidation) | | usePaginatedQueryPipeline | Query pipeline for paginated list operations | | useGqlQuery / useGqlSuspenseQuery | Typed query hooks that take a TypedDocumentNode and unwrap the root field | | useGqlMutation | Typed mutation hook; invalidates shorthand for meta.invalidates | | gqlQueryKey | Stable query key from a document + variables | | QueryMeta / MutationMeta / GqlVariables | Supporting types (featureId, invalidates, variable record) | | GqlQueryOptions / GqlSuspenseQueryOptions / GqlMutationOptions | Option types for the useGql* hooks (query key / fn omitted) |

Query failures are forwarded to the feature tracker via @bota-apps/fm; the GraphQLClient type comes from @bota-apps/gql-client. React and @tanstack/react-query are peer dependencies supplied by the app.

Part of the @bota-apps packages monorepo.