Studio Queries

supabase/studio-queries

React Query conventions for data fetching in Supabase Studio. Use when writing or reviewing query hooks, mutation hooks, or query keys in apps/studio/data/ — including adding the first fetch or mutation for a new API endpoint or resource. Covers queryOptions pattern, keys.ts structure, mutation hook template, and imperative fetching.

1k tokens

context cost

the whole folder, loaded on every use

files

instructions only

copies elsewhere

how many repositories repackaged it

107520

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/supabase/supabase --skill studio-queries

The instruction itself

7 sections, as written by the author

Studio Queries & Mutations (React Query)

Follow the patterns in apps/studio/data/. Reference examples:

Query options: apps/studio/data/table-editor/table-editor-query.ts
Mutation hook: apps/studio/data/edge-functions/edge-functions-update-mutation.ts
Keys: apps/studio/data/edge-functions/keys.ts

Query Keys

Define a keys.ts per domain. Export *Keys helpers using array keys with as const. Never inline query keys in components.

export const edgeFunctionsKeys = {
  list: (projectRef: string | undefined) => ['projects', projectRef, 'edge-functions'] as const,
  detail: (projectRef: string | undefined, slug: string | undefined) =>
    ['projects', projectRef, 'edge-function', slug, 'detail'] as const,
}

Query Options (preferred pattern)

Use queryOptions from @tanstack/react-query. This gives type safety and works with both useQuery() and queryClient.fetchQuery().

Rules:

Export XVariables, XData, and XError types (prefixed with the domain name)
Implement a private getX(variables, signal?) function:
Throws if required variables are missing
Passes signal for cancellation
Calls handleError(error) on failure (which throws); returns data on success
Not exported — use queryClient.fetchQuery(xQueryOptions(...)) for imperative fetching
Export xQueryOptions() using queryOptions
Gate with enabled so the query doesn't run until required variables exist
Platform-only queries: include IS_PLATFORM from lib/constants in enabled
Don't add extra params to xQueryOptions — callers override by destructuring: { ...xQueryOptions(vars), enabled: true }

import { queryOptions } from '@tanstack/react-query'

import { xKeys } from './keys'
import { get, handleError } from '@/data/fetchers'
import { IS_PLATFORM } from '@/lib/constants'
import { ResponseError } from '@/types'

export type XVariables = { projectRef?: string }
export type XError = ResponseError

async function getX({ projectRef }: XVariables, signal?: AbortSignal) {
  if (!projectRef) throw new Error('projectRef is required')
  const { data, error } = await get('/v1/projects/{ref}/x', {
    params: { path: { ref: projectRef } },
    signal,
  })
  if (error) handleError(error)
  return data
}

export type XData = Awaited<ReturnType<typeof getX>>

export const xQueryOptions = ({ projectRef }: XVariables) =>
  queryOptions({
    queryKey: xKeys.list(projectRef),
    queryFn: ({ signal }) => getX({ projectRef }, signal),
    enabled: IS_PLATFORM && typeof projectRef !== 'undefined',
  })

Using Query Options in Components

import { useQuery } from '@tanstack/react-query'

import { xQueryOptions } from '@/data/x/x-query'

const { data, isPending, isError } = useQuery(xQueryOptions({ projectRef: project?.ref }))

Imperative Fetching (outside React or in callbacks)

const queryClient = useQueryClient()
const { data: project } = useSelectedProjectQuery()

const handleClick = useCallback(
  async (id: number) => {
    const data = await queryClient.fetchQuery(xQueryOptions({ id, projectRef: project?.ref }))
    // use data...
  },
  [project?.ref, queryClient]
)

Mutation Hook

Export a Variables type with projectRef, identifiers, and payload
Implement a private updateX(vars) function with required variable validation and handleError
Wrap in useXMutation():
Accepts UseMutationOptions (omit mutationFn)
Invalidates list() + detail() keys in onSuccess with await Promise.all([...])
Defaults to toast.error(...) when onError isn't provided

import { useMutation, UseMutationOptions, useQueryClient } from '@tanstack/react-query'
import toast from 'react-hot-toast'

import { xKeys } from './keys'

type XUpdateVariables = { projectRef: string; slug: string; payload: XPayload }

export const useXUpdateMutation = ({
  onSuccess,
  onError,
  ...options
}: UseMutationOptions<XData, XError, XUpdateVariables> = {}) => {
  const queryClient = useQueryClient()
  return useMutation({
    mutationFn: updateX,
    async onSuccess(data, variables, context) {
      await Promise.all([
        queryClient.invalidateQueries({
          queryKey: xKeys.detail(variables.projectRef, variables.slug),
        }),
        queryClient.invalidateQueries({ queryKey: xKeys.list(variables.projectRef) }),
      ])
      await onSuccess?.(data, variables, context)
    },
    async onError(error, variables, context) {
      if (onError === undefined) toast.error(`Failed to update: ${error.message}`)
      else onError(error, variables, context)
    },
    ...options,
  })
}

Component Usage

Use React Query v5 flags: isPending for initial load, isFetching for background refetches
Render states explicitly in order: pending → error → success

How to use it

Copy the folder

Take supabase/studio-queries from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.