Cursor Rules for Nuxt: Rendering, Data, and Components

Cursor rules for Nuxt tell the AI assistant which rendering mode the project uses, which data fetching composables are standard, how components are organized, and which test command to run. Nuxt's flexibility — SSR, SSG, hybrid, or SPA — means the correct approach depends heavily on what your project has already decided, not just what is possible in the framework.

Tools like fenbs keep the rendering and product decisions that explain those conventions outside the codebase. An assistant that reads both the rules and the project context in fenbs understands not just the file structure but the reasoning behind it.

What Nuxt rules should cover

• Rendering mode: SSR, SSG, ISR, hybrid, or SPA, and which routes or page types use which mode.
• Data fetching: useFetch, useAsyncData, $fetch, or a custom composable, and when each is appropriate.
• Server versus client code: what goes in server/ versus app/, and which APIs are available in each.
• Component conventions: naming, where composables live, whether the project uses an auto-import layer.
• State management: Pinia, useState, or global composables, and where stores are defined.
• Test setup: Vitest, Nuxt test utilities, or another runner, and the exact test command.

A starting template

# Nuxt project rules

## Build and run
- Dev: pnpm run dev
- Build: pnpm run build
- Test: pnpm run test

## Rendering
- This project uses SSR for all pages except those in pages/spa/
  which are client-only (definePageMeta({ ssr: false })).

## Data fetching
- Use useFetch() for data that needs to be fetched on the server.
- Use $fetch() for client-side-only requests (inside onMounted or event handlers).
- Do not use the old asyncData() pattern; use useAsyncData() if you need
  a custom key.

## Server code
- API routes live in server/api/. Do not access the database from pages.
- Server utilities live in server/utils/ and are auto-imported.

## Components
- Components are auto-imported from components/. Do not import them manually.
- Composables are auto-imported from composables/. Do not import them manually.
- Use PascalCase for component names, camelCase for composable names.

## State
- Use Pinia stores for shared state. Stores live in stores/.
- Use useState() only for simple SSR-safe reactive state.

## Do not touch
- .nuxt/ (generated by Nuxt, managed automatically)

Server and client boundary rules

The server-client boundary is the most important concept to get right in a Nuxt project. An assistant that uses process.env in a client-side composable will produce code that works in development (where Vite provides it) but breaks in production. An assistant that calls a database directly from a page component bypasses any authentication your API routes enforce.

Write the boundary rules with specific examples of what belongs on each side. "API calls that require authentication go through server/api/" is clearer than "be careful about server-side access." The more concrete the rule, the more reliably an assistant follows it. See Cursor rules for AI projects for how to structure rules for full-stack frameworks.

TypeScript and type safety in Nuxt

Nuxt generates TypeScript types for routes, components, and composables through its type-generation step. An assistant that bypasses these generated types and writes manual type assertions will produce code that does not benefit from Nuxt's automatic type safety. Add rules about where to find the generated types and how to use them.

• Generated route types are in .nuxt/types/; use NuxtLinkProps and navigateTo() with typed routes.
• Component props should use defineProps() with TypeScript types, not the options API object syntax.
• Do not import from .nuxt/ directly; import from #app or #imports as the auto-import system intends.
• Run nuxi typecheck before committing to verify the generated types are valid.

Plugin and module conventions

Nuxt plugins and modules run at specific times in the application lifecycle. A plugin that uses browser APIs without checking for a client-only context will crash during server-side rendering. Add a rule: any plugin that uses window, document, or other browser globals must include a if (process.client) guard or use the defineNuxtPlugin client-only option.

Third-party Nuxt modules have their own configuration conventions. If your project uses a module like Nuxt Content, Nuxt i18n, or Nuxt Image, add the relevant conventions so the assistant knows how to create content files, translation keys, or optimized image components without breaking the module's expected structure.

Rendering decisions and fenbs

Why does the project use SSR for the marketing pages but SPA mode for the app? Why was hybrid rendering chosen over a full SSG build? Those decisions were made at a specific point and for specific reasons. They shape every new page and route an assistant creates.

Recording them in fenbs as Decisions means an assistant working on a new page can read the current rendering strategy before choosing a rendering mode, rather than defaulting to whatever the last page used. When the strategy changes, a new Decision captures the change.

How to set up Nuxt rules with fenbs

1. Create a free account and add your Nuxt project to fenbs. Record the rendering and architecture decisions: which mode is used for which parts of the app, the data fetching approach, the state management choice.
2. Add the template above to your project's .cursor/rules/ directory and update it with the actual rendering configuration and composable conventions your project uses.
3. Connect Cursor to fenbs over MCP from Integrations. Ask the assistant to read the project context at session start before creating any new pages, components, or API routes.
4. When the rendering strategy changes — adding a new SPA section, migrating to SSG for more pages — update the Decision in fenbs and the rules file.

What to watch for

Nuxt's auto-import system is a common source of confusion for AI assistants. An assistant that explicitly imports a component or composable that Nuxt provides automatically creates unnecessary imports that may shadow the auto-imported version. The rule "do not import auto-imported modules manually" is one of the most useful rules you can add for a Nuxt project.

The .nuxt/ directory is generated by Nuxt and changes every time you run a build or dev server. Add an explicit rule that this directory must never be modified manually. The same applies to any other generated directory your project uses.