Skip to content

project rulesFrontendnuxtvue

Nuxt Rules

Project rules for Nuxt 3: directory conventions, auto imports, useFetch data loading, Nitro server routes and per-route rendering modes.

npx workspacetemplates add nuxt-rules --tool claude-code

Writes 1 file to your project root

CLAUDE.mdadd to your file21 lines · 1.4 KBFile
# Project rules: Nuxt 3

## Structure
- Respect the directories: `pages/` for routes, `layouts/`, `components/`, `composables/`, `middleware/`, `plugins/`, `server/api/` and `server/utils/`. Do not add manual imports for what auto-import covers.
- Name composables `useThing`. Put shared types in `types/`. Use TypeScript everywhere and run `nuxi typecheck`.

## Data loading
- Use `useFetch` or `useAsyncData` with a unique key in components and pages so data is fetched once on the server and reused on the client. Use `$fetch` for event handlers and actions, not for initial render data.
- Handle `pending` and `error` in the template. Use `lazy` when a page can render before the data arrives.
- Keep shared state in `useState` with a key, never in a module-level variable (it leaks between requests on the server).

## Server routes
- Write handlers in `server/api/` with `defineEventHandler`. Validate input with Zod through `readValidatedBody` or `getValidatedQuery`, and throw `createError` with a status code.
- Put private keys in `runtimeConfig` (server only) and expose only values under `runtimeConfig.public`.

## Rendering
- Choose per route with `routeRules`: prerender for static pages, `swr` or `isr` for cacheable ones, `ssr: false` only for client-only tools.
- Wrap browser-only code in `onMounted` or `<ClientOnly>` to avoid hydration mismatches.

## Before finishing
- Run `nuxi typecheck`, the linter, the tests and `nuxi build`.

What it does

These rules help an agent follow the conventions Nuxt already provides, instead of rebuilding them. Pages, layouts, composables and server routes each have a folder, and the agent is told to use it.

They also cover data loading and rendering choices, where mistakes cause duplicate requests, hydration errors or secrets reaching the browser.

Example

you › Add a blog index page that lists posts from our CMS

agent › The agent adds pages/blog/index.vue with useFetch against a server route that hides the CMS key in runtimeConfig, marks the route with swr caching and handles loading and error states.

Questions

Why not call $fetch in setup?
It runs again on the client after server rendering, so the page makes the request twice. useFetch transfers the server result instead.
Does it apply to Nuxt 2?
No. Folder names and data APIs changed in Nuxt 3, so these rules would mislead an agent on version 2.
  • .NET Blazor Rules

    Project rulescsharp

    Free
  • Angular Rules

    Project rulesangular

    Free
  • Astro Rules

    Project rulesastro

    Free
  • Electron Rules

    Project ruleselectron

    Free