1# Nuxt Composables & Utilities
2 
3## When to Use
4 
5Working with Nuxt-specific composables, URL handling, navigation, or data fetching.
6 
7## URL & Request Handling
8 
9### useRequestURL()
10 
11**ALWAYS use `useRequestURL()` instead of `window.origin` or `window.location`:**
12 
13```ts
14// ✅ Correct - works SSR + client
15const url = useRequestURL()
16console.log(url.origin) // https://example.com
17console.log(url.pathname) // /users/123
18console.log(url.search) // ?tab=profile
19 
20// ❌ Wrong - breaks on SSR, not available server-side
21const origin = window.origin
22const path = window.location.pathname
23```
24 
25**Why:** `window` is undefined during SSR. `useRequestURL()` works everywhere.
26 
27### useRequestURL() Patterns
28 
29```ts
30// Get full URL
31const url = useRequestURL()
32const fullUrl = url.href // https://example.com/users/123?tab=profile
33 
34// Get origin (base URL)
35const baseUrl = url.origin // https://example.com
36 
37// Get path
38const path = url.pathname // /users/123
39 
40// Get query params (use useRoute() instead for better typing)
41const params = url.searchParams
42const tab = params.get('tab') // 'profile'
43 
44// Build absolute URL
45const apiUrl = `${url.origin}/api/users`
46```
47 
48## Navigation Composables
49 
50### navigateTo()
51 
52```ts
53// Navigate to route
54await navigateTo('/about')
55 
56// Type-safe navigation
57await navigateTo({ name: '/users/[userId]', params: { userId: '123' } })
58 
59// External URL
60await navigateTo('https://nuxt.com', { external: true })
61 
62// Replace history
63await navigateTo('/login', { replace: true })
64 
65// Open in new tab
66await navigateTo('/docs', { open: { target: '_blank' } })
67 
68// Server-side redirect
69return navigateTo('/login') // in middleware or server route
70```
71 
72### useRouter()
73 
74```ts
75const router = useRouter()
76 
77// Navigate
78router.push({ name: '/users/[userId]', params: { userId: '123' } })
79 
80// Go back
81router.back()
82 
83// Go forward
84router.forward()
85 
86// Navigation guards
87router.beforeEach((to, from) => {
88  // Guard logic
89})
90```
91 
92### useRoute()
93 
94```ts
95// Generic route
96const route = useRoute()
97 
98// Typed route (preferred)
99const route = useRoute('/users/[userId]')
100 
101// Access params
102const userId = route.params.userId
103 
104// Access query
105const tab = route.query.tab
106 
107// Access meta
108const requiresAuth = route.meta.requiresAuth
109```
110 
111## Data Fetching
112 
113### useFetch()
114 
115```ts
116// Basic fetch
117const { data, error, pending, refresh } = await useFetch('/api/users')
118 
119// With params
120const { data } = await useFetch('/api/users', {
121  query: { page: 1, limit: 10 }
122})
123 
124// With key for deduplication
125const { data } = await useFetch(`/api/users/${userId}`, {
126  key: `user-${userId}`
127})
128 
129// Lazy fetch (doesn't block navigation)
130const { data } = await useLazyFetch('/api/users')
131 
132// Watch and refetch
133const page = ref(1)
134const { data } = await useFetch('/api/users', {
135  query: { page },
136  watch: [page]
137})
138 
139// Cancel requests with AbortController signal (Nuxt 4.2+)
140const controller = new AbortController()
141const { data } = await useFetch('/api/users', {
142  signal: controller.signal
143})
144// Later: controller.abort() to cancel the request
145 
146// Manual cancellation via execute/refresh
147const { data, execute } = await useFetch('/api/users', { immediate: false })
148const abortController = new AbortController()
149await execute({ signal: abortController.signal })
150// Later: abortController.abort() to cancel
151```
152 
153### useAsyncData()
154 
155```ts
156// Custom async logic
157const { data, error, pending, refresh } = await useAsyncData('users', async () => {
158  const response = await $fetch('/api/users')
159  return response.filter(u => u.active)
160})
161 
162// Lazy version
163const { data } = await useLazyAsyncData('users', async () => {
164  return await $fetch('/api/users')
165})
166 
167// Cancel with AbortController (Nuxt 4.2+)
168const controller = new AbortController()
169const { data } = await useAsyncData('users', async () => {
170  return await $fetch('/api/users', { signal: controller.signal })
171})
172// Later: controller.abort() to cancel
173 
174// Custom cache logic with getCachedData
175const { data } = await useAsyncData('users',
176  async () => $fetch('/api/users'),
177  {
178    getCachedData: (key) => {
179      // Return cached data or null/undefined to trigger fetch
180      const cached = useNuxtData(key)
181      return cached.data.value
182    }
183  }
184)
185 
186// Deep reactivity for nested objects
187// Default is shallow in Nuxt 4 (was deep in Nuxt 3)
188const { data } = await useAsyncData('user',
189  async () => $fetch('/api/user'),
190  {
191    deep: true // Makes nested properties reactive
192  }
193)
194 
195// Deduplication strategies (Nuxt 4.2+)
196const { data } = await useAsyncData('users',
197  async () => $fetch('/api/users'),
198  {
199    dedupe: 'cancel' // Cancel existing requests when new one starts
200    // dedupe: 'defer' // Prevent new requests while one is pending
201  }
202)
203 
204// Manual cancellation via execute/refresh
205const { data, execute } = await useAsyncData('users',
206  async ({ signal }) => $fetch('/api/users', { signal }),
207  { immediate: false }
208)
209const abortController = new AbortController()
210await execute({ signal: abortController.signal })
211// Later: abortController.abort() to cancel
212```
213 
214## State Management
215 
216### useState()
217 
218```ts
219// Create shared state
220const counter = useState('counter', () => 0)
221 
222// Use in components
223counter.value++
224 
225// With type
226const user = useState<User | null>('user', () => null)
227```
228 
229## App Context
230 
231### useNuxtApp()
232 
233```ts
234const nuxtApp = useNuxtApp()
235 
236// Access provided values
237const { $api, $hello } = nuxtApp
238 
239// Access hooks
240nuxtApp.hook('page:finish', () => {
241  console.log('Page loaded')
242})
243 
244// Access Vue app
245nuxtApp.vueApp.use(SomePlugin)
246```
247 
248### useRuntimeConfig()
249 
250```ts
251// Access runtime config
252const config = useRuntimeConfig()
253 
254// Public config (client + server)
255const apiBase = config.public.apiBase
256 
257// Private config (server only)
258const apiSecret = config.apiSecret // undefined on client
259```
260 
261## Head Management
262 
263### useHead()
264 
265```ts
266// Set page meta
267useHead({
268  title: 'User Profile',
269  meta: [
270    { name: 'description', content: 'View user profile' },
271    { property: 'og:title', content: 'User Profile' }
272  ],
273  link: [
274    { rel: 'canonical', href: 'https://example.com/profile' }
275  ]
276})
277 
278// Dynamic values
279const user = ref({ name: 'John' })
280useHead({
281  title: () => `${user.value.name}'s Profile`
282})
283```
284 
285### useSeoMeta()
286 
287```ts
288// Cleaner SEO meta
289useSeoMeta({
290  title: 'User Profile',
291  description: 'View user profile',
292  ogTitle: 'User Profile',
293  ogDescription: 'View user profile',
294  ogImage: 'https://example.com/image.jpg',
295  twitterCard: 'summary_large_image'
296})
297```
298 
299## Best Practices
300 
301- **Use useRequestURL()** NOT window.origin/location
302- **Type routes** with useRoute('/path/[param]')
303- **Use useFetch** for API calls (deduplication, SSR)
304- **Key your fetches** for proper caching
305- **useState for shared state** across components
306- **useSeoMeta** for cleaner SEO tags
307 
308## Common Mistakes
309 
310| ❌ Wrong                     | ✅ Right                                              |
311| ---------------------------- | ----------------------------------------------------- |
312| `window.origin`              | `useRequestURL().origin`                              |
313| `window.location.pathname`   | `useRequestURL().pathname`                            |
314| `fetch()` in components      | `useFetch()` or `useAsyncData()`                      |
315| `router.push('/path/' + id)` | `router.push({ name: '/path/[id]', params: { id } })` |
316| Duplicate fetches            | Use `key` parameter                                   |
317 
318## Resources
319 
320- Nuxt composables: https://nuxt.com/docs/api/composables/use-fetch
321- Data fetching: https://nuxt.com/docs/getting-started/data-fetching
322- useRequestURL: https://nuxt.com/docs/api/composables/use-request-url
323- **For NuxtTime, NuxtLink, NuxtImg:** See nuxt-components.md
324