orval-tanstack-query

name	orval-tanstack-query
description	Orval code generation + TanStack Query patterns for the @repo/api-client package. Use when regenerating TypeScript hooks from openapi.json, implementing the custom fetcher, or consuming generated hooks in apps/web. Triggers on tasks involving orval.config.ts, api-client generation, customFetcher, TanStack Query hooks from the Laravel API, or @repo/api-client imports.
frameworks	["orval","tanstack-query","nextjs"]
languages	["typescript"]
category	api
updated	"2026-04-29T00:00:00.000Z"

Orval + TanStack Query Skill

Quick Reference

When to Use: Regenerating TypeScript hooks from openapi.json, implementing the fetcher, or consuming @repo/api-client hooks

Source of truth: apps/laravel/openapi.json → Orval → packages/api-client/src/generated/

Regenerate command: pnpm -F @repo/api-client generate

Package Structure

packages/api-client/
├── orval.config.ts          # Orval config (input: openapi.json, output: generated/)
├── src/
│   ├── index.ts             # Re-exports generated code + mutator types
│   ├── mutator/
│   │   └── custom-fetcher.ts  # Injectable fetcher contract
│   └── generated/           # AUTO-GENERATED — do not edit manually
│       ├── api.ts           # All hooks, query keys, mutation functions
│       └── *.ts             # Per-endpoint type schemas
└── package.json

Orval Config

// packages/api-client/orval.config.ts
import { defineConfig } from 'orval'

export default defineConfig({
  laravelApi: {
    input: {
      target: '../../apps/laravel/openapi.json',  // Source of truth
    },
    output: {
      mode: 'split',
      target: './src/generated/api.ts',
      schemas: './src/generated',
      client: 'react-query',
      clean: true,
      prettier: true,
      override: {
        mutator: {
          path: './src/mutator/custom-fetcher.ts',
          name: 'customFetcher',
        },
        query: {
          useQuery: true,
          useMutation: true,
          signal: true,
        },
      },
    },
  },
})

Custom Fetcher Contract

The customFetcher is the only HTTP implementation you need to provide. It's injected once at app startup.

// packages/api-client/src/mutator/custom-fetcher.ts

/** The interface consumers must implement */
export type CustomFetcher = <T>(url: string, init: RequestInit) => Promise<T>

let _fetcher: CustomFetcher | undefined

/** Call this once before making any API requests */
export function configureFetcher(fetcher: CustomFetcher): void {
  _fetcher = fetcher
}

/** Called by every orval-generated hook */
export const customFetcher = <T>(config: OrvalConfig): Promise<T> => {
  if (!_fetcher) {
    throw new Error('[@repo/api-client] No fetcher configured. Call configureFetcher() before making API requests.')
  }
  // Adapts orval's internal config to (url, RequestInit)
  const { url, method, params, headers: configHeaders, data, signal } = config
  const fullUrl = params ? `${url}?${new URLSearchParams(...)}` : url
  return _fetcher<T>(fullUrl, {
    method: method.toUpperCase(),
    headers: { Accept: 'application/json', ...configHeaders },
    signal,
    ...(data !== undefined ? { body: JSON.stringify(data) } : {}),
  })
}

Web App Fetcher Implementation (Sanctum)

// apps/web/services/sanctum/browser-fetcher.ts
import type { CustomFetcher } from "@repo/api-client"

export const sanctumBrowserFetcher: CustomFetcher = async <T>(
  url: string,
  init: RequestInit
): Promise<T> => {
  const origin = new URL(env.NEXT_PUBLIC_API_BASE_URL).origin
  const method = ((init.method as string) || "GET").toUpperCase()

  // Auto-fetch CSRF cookie and set X-XSRF-TOKEN header on mutations
  if (method !== "GET" && method !== "HEAD") {
    let token = readXsrfToken()
    if (!token) {
      await fetch(`${origin}/sanctum/csrf-cookie`, { credentials: "include" })
      token = readXsrfToken()
    }
    if (token) {
      const headers = new Headers(init.headers as HeadersInit)
      headers.set("X-XSRF-TOKEN", token)
      init = { ...init, headers }
    }
  }

  const response = await fetch(`${origin}${url}`, {
    ...init,
    credentials: "include",  // Always include cookies for session auth
  })
  // Handle 401 redirect, error responses, JSON parsing...
  return response.json() as Promise<T>
}

Wire it up once at app startup:

// apps/web/app/layout.tsx or a client component
import { configureFetcher } from "@repo/api-client"
import { sanctumBrowserFetcher } from "@/services/sanctum/browser-fetcher"

configureFetcher(sanctumBrowserFetcher)

Using Generated Hooks

// apps/web/features/todos/api/todos.hooks.ts
import {
  useGetApiV1Todos,
  usePostApiV1Todos,
  usePatchApiV1TodosId,
  useDeleteApiV1TodosId,
} from "@repo/api-client"

// List query
export function useTodosQuery() {
  return useGetApiV1Todos()
}

// Create mutation
export function useCreateTodoMutation() {
  const queryClient = useQueryClient()
  return usePostApiV1Todos({
    mutation: {
      onSuccess: () => queryClient.invalidateQueries({ queryKey: getGetApiV1TodosQueryKey() }),
    },
  })
}

// Update mutation
export function useUpdateTodoMutation(id: number) {
  const queryClient = useQueryClient()
  return usePatchApiV1TodosId(id, {
    mutation: {
      onSuccess: () => queryClient.invalidateQueries({ queryKey: getGetApiV1TodosQueryKey() }),
    },
  })
}

// Delete mutation
export function useDeleteTodoMutation() {
  const queryClient = useQueryClient()
  return useDeleteApiV1TodosId({
    mutation: {
      onSuccess: () => queryClient.invalidateQueries({ queryKey: getGetApiV1TodosQueryKey() }),
    },
  })
}

Generated Hook Naming Convention

Orval generates hook names from the HTTP method + path:

Endpoint	Generated Hook
GET /api/v1/todos	useGetApiV1Todos
POST /api/v1/todos	usePostApiV1Todos
GET /api/v1/todos/{id}	useGetApiV1TodosId
PATCH /api/v1/todos/{id}	usePatchApiV1TodosId
DELETE /api/v1/todos/{id}	useDeleteApiV1TodosId
POST /api/v1/auth/mobile/login	usePostApiV1AuthMobileLogin

Query keys follow the same pattern with a get prefix:

• getGetApiV1TodosQueryKey() — for useGetApiV1Todos

Regeneration Workflow

# 1. Modify Laravel API (controller, route, Form Request)
# 2. Regenerate OpenAPI spec
pnpm -F @repo/laravel openapi:generate

# 3. Regenerate TypeScript hooks
pnpm -F @repo/api-client generate

# 4. Build the package (needed by apps/web)
pnpm -F @repo/api-client build

# Or regenerate + build in one step from root
pnpm build --filter=@repo/api-client

Package Exports

// packages/api-client/src/index.ts
// Re-export generated hooks + types
export * from './generated/api'
// Re-export fetcher contract for consumers
export type { CustomFetcher } from './mutator/custom-fetcher'
export { configureFetcher } from './mutator/custom-fetcher'

Adding a New API Endpoint Checklist

1. Implement Laravel controller + route
2. Add Scribe annotations (@group, @bodyParam, @response)
3. Run pnpm -F @repo/laravel openapi:generate (commits openapi.json)
4. Run pnpm -F @repo/api-client generate (regenerates src/generated/)
5. Import and use the new useXxx hook in apps/web/features/[feature]/api/
6. Commit all three: PHP code + openapi.json + generated TypeScript