Nuxt

Pathrule2 Rules • 2 Memories • 1 Skill

An opinionated bundle for Nuxt 4 on Vue 3 that keeps agents on the current API surface. It covers when to use useFetch, useAsyncData, and $fetch, how to write Nitro server routes, and how to keep secrets and client-only code out of the universal render.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

nuxt-review

app/

Use useFetch and useAsyncData for render data, not raw $fetch

Nuxt 4 SSR-safe and auto-import conventions

Nuxt 4 directory layout and runtimeConfig

server/

Define Nitro routes with defineEventHandler, one handler per file

Rules

Use useFetch and useAsyncData for render data, not raw $fetch/apphighstrictFetch initial component data through the SSR-aware composables so it survives hydration.

1	Use `useFetch` and `useAsyncData` for any data that feeds the initial render. They transfer the server payload to the client and dedupe, while raw `$fetch` re-runs on hydration.
2
3	- Use `useFetch(url)` for plain endpoint calls. It keys on the URL automatically and infers types from `server/api`.
4	- Use `useAsyncData(key, fn)` when you wrap an SDK, combine endpoints, or shape the payload. Always pass an explicit unique `key`.
5	- Reserve bare `$fetch` for client-side event handlers (submit, click), never for initial data.
6	- Do not pass `$fetch` directly as the `useFetch` handler. It breaks caching and dedup.

Define Nitro routes with defineEventHandler, one handler per file/serverhighstrictWrite server/api handlers the Nitro way and keep secrets server-side.

1	Files in `server/api` are auto-prefixed with `/api`; files in `server/routes` map at the root. Export one `defineEventHandler` per file.
2
3	- Encode the method in the filename (`users.get.ts`, `users.post.ts`) instead of branching on `event.method`.
4	- Read inputs with `getQuery`, `getRouterParam`, and `await readBody(event)` from `h3`; never parse the raw request yourself.
5	- Throw `createError({ statusCode, statusMessage })` for failures so Nitro returns a proper error response.
6	- Access secrets via `useRuntimeConfig(event)`, passing `event` so env overrides apply at runtime.

Memories

Nuxt 4 SSR-safe and auto-import conventions/appWhat runs where, plus how auto-imports change how you write components.

1	Nuxt 4 renders universally by default, so component setup runs on both server and client. Guard browser-only access.
2
3	- Wrap `window`, `document`, `localStorage`, and similar in `if (import.meta.client)` or `onMounted`, which only runs on the client.
4	- Use `import.meta.server` / `import.meta.client` for branch logic; the legacy `process.server` / `process.client` flags are gone.
5	- Composables, components, and `utils`/`composables` exports are auto-imported. Do not add manual imports for them; `$fetch` is the global auto-imported alias for `ofetch`.
6	- In Nuxt 4 the `data` from `useFetch`/`useAsyncData` is a `shallowRef`. Replace the value to trigger reactivity rather than mutating nested fields in place.

Nuxt 4 directory layout and runtimeConfig/appWhere source lives in Nuxt 4 and how to split public vs private config.

1	Nuxt 4 moved app source under `app/` (`app/pages`, `app/components`, `app/composables`) while `server/`, `modules/`, `layers/`, and `shared/` stay at the project root.
2
3	- Put API handlers in `server/api`, shared cross-runtime helpers in `shared/`, and Vue UI under `app/`.
4	- Define secrets in `runtimeConfig` (server-only) and browser-safe values in `runtimeConfig.public`. Never put tokens in `public`.
5	- Override config at runtime with `NUXT_*` env vars (for example `NUXT_API_SECRET`, `NUXT_PUBLIC_SITE_URL`).
6	- Read config with `useRuntimeConfig()` in components and `useRuntimeConfig(event)` in server handlers.

Skills

nuxt-review/rootPre-merge checklist for Nuxt 4 data fetching, server routes, and SSR safety.

1	---
2	name: nuxt-review
3	description: Review a Nuxt 4 change for correct data fetching, Nitro server routes, runtimeConfig secret handling, and SSR-safe code before merging.
4	---
5
6	# Nuxt 4 review
7
8	- [ ] Initial render data uses `useFetch` or `useAsyncData`, not raw `$fetch`.
9	- [ ] Every `useAsyncData` call passes an explicit, unique `key`.
10	- [ ] `$fetch` is only used in client event handlers, never for initial data.
11	- [ ] `lazy: true` / `server: false` choices match the data's SEO and blocking needs.
12	- [ ] Server handlers use `defineEventHandler` with method-suffixed filenames.
13	- [ ] Inputs read via `getQuery`, `getRouterParam`, `readBody`; errors via `createError`.
14	- [ ] Secrets live in `runtimeConfig` (server-only), never `runtimeConfig.public`.
15	- [ ] `useRuntimeConfig(event)` is used inside server handlers.
16	- [ ] Browser-only APIs are guarded with `import.meta.client` or `onMounted`.
17	- [ ] No manual imports added for auto-imported composables, components, or utils.

Why this pattern

AI agents reach for stale Nuxt 2 and 3 habits, misuse the data-fetching composables, and leak secrets or break hydration in the universal render.

Built for Teams building full-stack Nuxt 4 apps on Vue 3 with Nitro.

Keeps your assistant from:

Calling raw $fetch for initial page data, causing double fetches and hydration mismatches
Reading server-only secrets through runtimeConfig.public or env vars on the client
Touching window, document, or localStorage during SSR without a client guard

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-06-09