useFetch

Source
SSR에 친화적인 컴포저블로 API 엔드포인트에서 데이터를 가져옵니다.

이 컴포저블은 useAsyncData와 $fetch를 편리하게 감싸는 래퍼를 제공합니다. URL과 fetch 옵션을 기반으로 자동으로 키를 생성하고, 서버 라우트를 기반으로 요청 URL에 대한 타입 힌트를 제공하며, API 응답 타입을 추론합니다.

useFetch는 setup 함수, 플러그인 또는 라우트 미들웨어에서 직접 호출하도록 설계된 컴포저블입니다. 반응형 컴포저블을 반환하며, 응답을 Nuxt 페이로드에 추가하여 페이지가 하이드레이션될 때 클라이언트 측에서 데이터를 다시 가져오지 않고도 서버에서 클라이언트로 전달될 수 있도록 처리합니다.

Usage

app/pages/modules.vue
<script setup lang="ts">
const { data, status, error, refresh, clear } = await useFetch('/api/modules', {
  pick: ['title'],
})
</script>
커스텀 useFetch 래퍼를 사용하는 경우, 해당 컴포저블 내부에서 이를 await 하지 마세요. 예기치 않은 동작을 유발할 수 있습니다. 커스텀 비동기 데이터 패처를 만드는 방법에 대한 자세한 내용은 이 레시피를 참고하세요.
data, status, error는 Vue ref이며, <script setup> 내에서 사용할 때는 .value로 접근해야 합니다. 반면 refresh/execute와 clear는 일반 함수입니다.

query 옵션을 사용하면 쿼리에 검색 파라미터를 추가할 수 있습니다. 이 옵션은 unjs/ofetch에서 확장되었으며, URL 생성을 위해 unjs/ufo를 사용합니다. 객체는 자동으로 문자열화됩니다.

const param1 = ref('value1')
const { data, status, error, refresh } = await useFetch('/api/modules', {
  query: { param1, param2: 'value2' },
})

위 예시는 https://api.nuxt.com/modules?param1=value1&param2=value2를 결과로 생성합니다.

또한 인터셉터를 사용할 수도 있습니다:

const { data, status, error, refresh, clear } = await useFetch('/api/auth/login', {
  onRequest ({ request, options }) {
    // 요청 헤더 설정
    // ofetch >= 1.4.0에 의존한다는 점에 유의하세요 - lockfile을 새로 고쳐야 할 수 있습니다
    options.headers.set('Authorization', '...')
  },
  onRequestError ({ request, options, error }) {
    // 요청 에러 처리
  },
  onResponse ({ request, response, options }) {
    // 응답 데이터 처리
    localStorage.setItem('token', response._data.token)
  },
  onResponseError ({ request, response, options }) {
    // 응답 에러 처리
  },
})

Reactive Keys and Shared State

URL로 계산된 ref 또는 일반 ref를 사용할 수 있어, URL이 변경될 때 자동으로 업데이트되는 동적 데이터 패칭이 가능합니다:

app/pages/[id].vue
<script setup lang="ts">
const route = useRoute()
const id = computed(() => route.params.id)

// 라우트가 변경되어 id가 업데이트되면, 데이터가 자동으로 다시 fetch됩니다
const { data: post } = await useFetch(() => `/api/posts/${id.value}`)
</script>

여러 컴포넌트에서 동일한 URL과 옵션으로 useFetch를 사용하는 경우, 동일한 data, error, status ref를 공유합니다. 이는 컴포넌트 간의 일관성을 보장합니다.

useFetch로 생성된 키 기반 상태는 Nuxt 애플리케이션 전반에서 useNuxtData를 사용해 가져올 수 있습니다.
useFetch는 컴파일러에 의해 변환되는 예약된 함수 이름이므로, 직접 만든 함수의 이름을 useFetch로 지정해서는 안 됩니다.
useFetch에서 구조 분해 할당한 data 변수가 JSON으로 파싱된 객체가 아니라 문자열을 반환하는 경우, 컴포넌트에 import { useFetch } from '@vueuse/core와 같은 import 문이 포함되어 있지 않은지 확인하세요.
Read more in Docs > 4 X > Getting Started > Data Fetching.

Reactive Fetch Options

Fetch 옵션은 computed, ref 및 computed getter를 지원하는 반응형으로 제공할 수 있습니다. 반응형 fetch 옵션이 업데이트되면, 업데이트된 반응형 값으로 다시 fetch가 트리거됩니다.

const searchQuery = ref('initial')
const { data } = await useFetch('/api/search', {
  query: { q: searchQuery },
})
// 다시 fetch를 트리거함: /api/search?q=new%20search
searchQuery.value = 'new search'

필요하다면, watch: false를 사용해 이 동작을 비활성화할 수 있습니다:

const searchQuery = ref('initial')
const { data } = await useFetch('/api/search', {
  query: { q: searchQuery },
  watch: false,
})
// 다시 fetch를 트리거하지 않음
searchQuery.value = 'new search'

Type

Signature
export function useFetch<DataT, ErrorT> (
  url: string | Request | Ref<string | Request> | (() => string | Request),
  options?: UseFetchOptions<DataT>,
): Promise<AsyncData<DataT, ErrorT>>

type UseFetchOptions<DataT> = {
  key?: MaybeRefOrGetter<string>
  method?: MaybeRefOrGetter<string>
  query?: MaybeRefOrGetter<SearchParams>
  params?: MaybeRefOrGetter<SearchParams>
  body?: MaybeRefOrGetter<RequestInit['body'] | Record<string, any>>
  headers?: MaybeRefOrGetter<Record<string, string> | [key: string, value: string][] | Headers>
  baseURL?: MaybeRefOrGetter<string>
  server?: boolean
  lazy?: boolean
  immediate?: boolean
  getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
  deep?: boolean
  dedupe?: 'cancel' | 'defer'
  timeout?: number
  default?: () => DataT
  transform?: (input: DataT) => DataT | Promise<DataT>
  pick?: string[]
  $fetch?: typeof globalThis.$fetch
  watch?: MultiWatchSources | false
  timeout?: MaybeRefOrGetter<number>
}

type AsyncDataRequestContext = {
  /** 이 데이터 요청의 이유 */
  cause: 'initial' | 'refresh:manual' | 'refresh:hook' | 'watch'
}

type AsyncData<DataT, ErrorT> = {
  data: Ref<DataT | undefined>
  refresh: (opts?: AsyncDataExecuteOptions) => Promise<void>
  execute: (opts?: AsyncDataExecuteOptions) => Promise<void>
  clear: () => void
  error: Ref<ErrorT | undefined>
  status: Ref<AsyncDataRequestStatus>
}

interface AsyncDataExecuteOptions {
  dedupe?: 'cancel' | 'defer'
  timeout?: number
  signal?: AbortSignal
}

type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'

Parameters

  • URL (string | Request | Ref<string | Request> | () => string | Request): 가져올 URL 또는 요청입니다. 문자열, Request 객체, Vue ref, 또는 문자열/Request를 반환하는 함수가 될 수 있습니다. 동적 엔드포인트를 위한 반응성을 지원합니다.
  • options (object): fetch 요청에 대한 설정입니다. unjs/ofetch 옵션과 AsyncDataOptions를 확장합니다. 모든 옵션은 정적 값, ref, 또는 computed 값이 될 수 있습니다.
OptionTypeDefaultDescription
keyMaybeRefOrGetter<string>auto-gen중복 제거를 위한 고유 키입니다. 제공되지 않으면 URL과 옵션에서 생성됩니다.
methodMaybeRefOrGetter<string>'GET'HTTP 요청 메서드입니다.
queryMaybeRefOrGetter<SearchParams>-URL에 추가할 쿼리/검색 파라미터입니다. 별칭: params.
paramsMaybeRefOrGetter<SearchParams>-query의 별칭입니다.
bodyMaybeRefOrGetter<RequestInit['body'] | Record<string, any>>-요청 본문입니다. 객체는 자동으로 문자열화됩니다.
headersMaybeRefOrGetter<Record<string, string> | [key, value][] | Headers>-요청 헤더입니다.
baseURLMaybeRefOrGetter<string>-요청의 기본 URL입니다.
timeoutMaybeRefOrGetter<number>-요청을 중단하기 위한 밀리초 단위의 타임아웃입니다.
cacheboolean | string-캐시 제어입니다. boolean은 캐시를 비활성화하고, 또는 Fetch API 값(default, no-store 등)을 사용할 수 있습니다.
serverbooleantrue서버에서 fetch할지 여부입니다.
lazybooleanfalsetrue이면, 라우트 로드 후에 resolve되며(네비게이션을 차단하지 않음).
immediatebooleantruefalse이면, 요청이 즉시 실행되는 것을 방지합니다.
default() => DataT-비동기 처리가 완료되기 전 data의 기본값을 위한 팩토리입니다.
timeoutnumber-요청이 타임아웃되기 전까지 대기할 밀리초 수입니다(기본값은 undefined로, 타임아웃이 없음을 의미).
transform(input: DataT) => DataT | Promise<DataT>-resolve 후 결과를 변환하는 함수입니다.
getCachedData(key, nuxtApp, ctx) => DataT | undefined-캐시된 데이터를 반환하는 함수입니다. 기본값은 아래를 참고하세요.
pickstring[]-결과에서 지정된 키만 선택합니다.
watchMultiWatchSources | false-감시하고 자동으로 새로고침할 반응형 소스 배열입니다. false는 감시를 비활성화합니다.
deepbooleanfalse데이터를 deep ref 객체로 반환합니다.
dedupe'cancel' | 'defer''cancel'동일한 키를 한 번에 여러 번 fetch하는 것을 방지합니다.
$fetchtypeof globalThis.$fetch-커스텀 $fetch 구현입니다. Nuxt에서 커스텀 useFetch를 참고하세요.
모든 fetch 옵션은 computed 또는 ref 값으로 제공할 수 있습니다. 이 값들은 감시되며, 업데이트될 경우 새로운 값으로 자동으로 새 요청이 이루어집니다.

getCachedData 기본값:

const getDefaultCachedData = (key, nuxtApp, ctx) => nuxtApp.isHydrating
  ? nuxtApp.payload.data[key]
  : nuxtApp.static.data[key]

이는 nuxt.config에서 experimental.payloadExtraction이 활성화된 경우에만 데이터를 캐시합니다.

Return Values

NameTypeDescription
dataRef<DataT | undefined>비동기 fetch의 결과입니다.
refresh(opts?: AsyncDataExecuteOptions) => Promise<void>데이터를 수동으로 새로고침하는 함수입니다. 기본적으로 Nuxt는 refresh가 완료될 때까지 기다린 후에야 다시 실행할 수 있습니다.
execute(opts?: AsyncDataExecuteOptions) => Promise<void>refresh의 별칭입니다.
errorRef<ErrorT | undefined>데이터 가져오기에 실패했을 때의 에러 객체입니다.
statusRef<'idle' | 'pending' | 'success' | 'error'>데이터 요청의 상태입니다. 가능한 값은 아래를 참고하세요.
clear() => voiddata를 undefined(또는 제공된 경우 options.default()의 값)로 재설정하고, error를 undefined로 설정하며, status를 idle로 설정하고, 보류 중인 요청을 모두 취소합니다.

Status values

  • idle: 요청이 시작되지 않음(예: { immediate: false } 또는 서버 렌더링 시 { server: false })
  • pending: 요청이 진행 중
  • success: 요청이 성공적으로 완료됨
  • error: 요청이 실패함
서버에서 데이터를 fetch하지 않은 경우(예: server: false를 사용한 경우), 하이드레이션이 완료될 때까지 데이터는 가져오지지 않습니다. 이는 클라이언트 측에서 useFetch를 await하더라도, <script setup> 내에서 data는 null 상태로 남아 있음을 의미합니다.

Examples

Read and edit a live example in Docs > 4 X > Examples > Advanced > Use Custom Fetch Composable.
Read and edit a live example in Docs > 4 X > Examples > Features > Data Fetching.