agent-rules-kit

--- description: Core architectural concepts for Nuxt applications globs: <root>/app.vue,<root>/components/**/*.vue,<root>/components/**/*.ts,<root>/components/**/*.js alwaysApply: false --- # Nuxt Architecture Concepts This document outlines the core architectural concepts and patterns used in Nuxt.js applications in {projectPath}. ## Nuxt Framework Overview Nuxt is a meta-framework built on top of Vue.js that provides: - Server-side rendering (SSR) - Static site generation (SSG) - Client-side rendering (CSR) - File-based routing - Auto-imports - Server API routes - Optimized build process ## Rendering Modes Nuxt supports multiple rendering strategies: ### Universal Rendering (Default) - **Server-side rendering + hydration**: Pages first render on the server, then hydrate on the client - Provides the best SEO and initial load performance - Works in most scenarios ### Static Site Generation - Pre-renders all pages at build time - Creates static HTML files for deployment to CDNs - Configured via `nuxt.config.ts` ### Client-Side Rendering - For SPA-like behavior - Render components exclusively on the client - Less optimal for SEO - Use with `<ClientOnly>` component or in the Composition API ## Directory Structure Nuxt follows a conventional directory structure: ``` project/ ├── .nuxt/ # Build directory (auto-generated) ├── assets/ # Static assets that will be processed ├── components/ # Vue components (auto-imported) │ ├── ui/ # UI components │ └── feature/ # Feature-specific components ├── composables/ # Composable functions (auto-imported) ├── content/ # Markdown/JSON content for Nuxt Content ├── layouts/ # Layout components ├── middleware/ # Route middleware ├── pages/ # Application pages (file-based routing) ├── plugins/ # Nuxt plugins ├── public/ # Static assets served as-is ├── server/ # Server-side logic │ ├── api/ # API endpoints │ └── middleware/ # Server middleware ├── stores/ # Pinia stores ├── app.vue # The main application component ├── error.vue # Error page ├── nuxt.config.ts # Nuxt configuration └── package.json # Project dependencies ``` ## Auto-Imports One of Nuxt's key features is automatic imports: - **Components**: All files in `/components` are auto-imported - **Composables**: All files in `/composables` are auto-imported - **Plugins**: All files in `/plugins` are auto-loaded - **Nuxt APIs**: Built-in functions like `useState`, `useRoute`, etc. ## Routing Architecture Nuxt uses file-based routing in the `/pages` directory, with the file path determining the URL route. This system supports: - Static routes - Dynamic parameters - Nested routes - Catch-all routes - Route middleware ### Route Middleware Middleware runs before navigating to a route. They can be: - Named middleware (specific to certain routes) - Global middleware (applied to all routes) - Anonymous middleware (inline in page components) ## State Management Nuxt provides several approaches to state management: ### Local Component State For simple state within a component, use standard Vue reactivity and local state. ### Shared State with useState Nuxt provides `useState` for shared state across components, which works on both server and client. ### Pinia Stores (Recommended for Complex State) For larger applications, Pinia offers a more structured approach with: - State (reactive data) - Actions (methods that change state) - Getters (computed values based on state) ## Data Fetching Nuxt provides several ways to fetch data: ### useAsyncData Fetch data before a component renders, with caching and server-side support. ### useFetch Simplified API for common fetch scenarios, with automatic key generation. ### Server-Only Data Fetching For improved security and performance, certain operations can be restricted to server-side code only. ## Server Routes Define API endpoints in the `server/api` directory with automatic route mapping based on file names and HTTP methods. ## Layouts and Page Structure Nuxt provides a layered approach to page structure with: - Default layouts - Custom layouts per page - Nested layouts - Layout transitions ## Modularity and Organization For large Nuxt applications, consider organizing by feature instead of technical role to improve maintainability and code cohesion. ## Plugins Use plugins to add global functionality to the application. Plugins can: - Extend the Vue instance - Register global components - Provide functions to the application - Initialize external libraries ## Composables Create reusable logic with composables to share functionality across components. ## SEO and Meta Tags Manage SEO with the `useHead` composable to set: - Title and meta tags - Open Graph and social media tags - Link tags - Script tags - HTML attributes ## Error Handling Nuxt provides built-in error handling with: - Custom error pages - Standardized error objects - Error handling in data fetching - Server-side error logging ## Performance Patterns Key patterns for Nuxt performance: 1. **Code Splitting**: Automatic route-based code splitting 2. **Lazy Loading**: Import components with `defineAsyncComponent` 3. **Prefetching and Preloading**: Automatic for linked pages 4. **Image Optimization**: Using Nuxt Image module 5. **Caching Strategy**: Use appropriate headers for API responses ## Architecture Decision Framework Consider these factors when making architecture decisions: 1. **Rendering Strategy**: Choose based on content type and update frequency 2. **State Management**: Use built-in Nuxt state for simple cases, Pinia for complex 3. **API Strategy**: Decide between server routes, server functions or external APIs 4. **SEO Requirements**: Influence rendering choices and meta tag strategy 5. **Performance Goals**: Guide choices for lazy loading, caching, etc.