agent-rules-kit
Version:
Bootstrap of **Cursor** rules (`.mdc`) and mirror documentation (`.md`) for AI agent-guided projects.
316 lines (239 loc) • 7.24 kB
Markdown
---
description: Best practices for Nuxt applications
globs: <root>/app.vue,<root>/components/**/*.vue,<root>/components/**/*.ts,<root>/components/**/*.js
alwaysApply: false
---
# Nuxt Best Practices
This document outlines best practices for Nuxt.js applications in {projectPath}.
## Performance Best Practices
### Component Optimization
1. **Use Shallow Imports**: Import only what you need
```js
// Good
import { ref, computed } from 'vue';
// Avoid
import * as Vue from 'vue';
```
2. **Component Laziness**: Use lazy loading for non-critical components
```js
// In Nuxt's auto-imports, use a prefix of 'Lazy'
<LazyHeavyComponent v-if='isVisible' />;
// Or define explicitly
const HeavyComponent = defineAsyncComponent(() =>
import('./HeavyComponent.vue')
);
```
3. **Proper Keys**: Always use unique keys for v-for loops
```html
<div v-for="item in items" :key="item.id">{{ item.name }}</div>
```
4. **Cache Expensive Computations**:
```js
// Use computed properties for expensive operations
const filteredItems = computed(() =>
items.value.filter(complexFilterFunction)
);
```
### Route & Data Optimization
1. **Optimize Page Load**: Use `useAsyncData` with appropriate cache options
```js
const { data } = await useAsyncData('posts', () => $fetch('/api/posts'), {
// Cache for 1 minute
watch: false,
server: true,
transform: (posts) => posts.map(simplifyPost),
headers: { 'Cache-Control': 'max-age=60' },
});
```
2. **Prefetch Likely Routes**: Use prefetching for links that will likely be clicked
```html
<NuxtLink to="/popular-page" prefetch>Popular Page</NuxtLink>
```
3. **Minimize Watchers**: Avoid unnecessary reactive updates
```js
// Good - only updates when really needed
const { data } = await useAsyncData('data', () => fetchData(), {
watch: false, // Or watch specific dependencies only
});
```
## Code Organization
1. **Follow Modular Structure**:
- Group related components, composables, and services
- Create domain-specific directories for large applications
2. **Use Typed Interfaces**:
```ts
// types/index.ts
export interface User {
id: string;
name: string;
email: string;
}
// In components/composables
const user = ref<User | null>(null);
```
3. **Component Naming Conventions**:
- Use PascalCase for component files and imports
- Use kebab-case in templates
- Use prefix for component categories (e.g., `BaseButton`, `FormInput`)
4. **Keep Components Small and Focused**:
- Single responsibility principle
- Extract reusable logic to composables
- Extract complex UI parts to sub-components
## State Management
1. **Choose the Right Approach**:
- Component state (`ref`/`reactive`) for local state
- `useState` for simple shared state
- Pinia stores for complex state with actions
2. **Structure Pinia Stores Properly**:
```js
// stores/user.js
export const useUserStore = defineStore('user', {
state: () => ({
user: null,
isLoggedIn: false,
}),
actions: {
async login(credentials) {
// Implementation
},
logout() {
// Implementation
},
},
getters: {
fullName: (state) =>
state.user
? `${state.user.firstName} ${state.user.lastName}`
: '',
},
});
```
3. **Prefer Composition API Store Usage**:
```js
<script setup>
const userStore = useUserStore(); // Destructure with storeToRefs to
maintain reactivity const {(user, isLoggedIn)} = storeToRefs(userStore);
const {(login, logout)} = userStore;
</script>
```
## Server Routes
1. **Use Request Validation**:
```js
// server/api/users/index.post.js
export default defineEventHandler(async (event) => {
const body = await readBody(event);
// Validate request
if (!body.email || !body.password) {
throw createError({
statusCode: 400,
message: 'Email and password are required',
});
}
// Process valid request
return {
/* ... */
};
});
```
2. **Structure Server Routes Logically**:
- Follow REST conventions
- Group related endpoints
- Use HTTP methods appropriately
3. **Separate Business Logic**:
- Keep API handlers thin
- Extract complex logic to server/utils or server/services
## Testing
1. **Test Components in Isolation**:
```js
import { mount } from '@vue/test-utils';
import MyComponent from './MyComponent.vue';
test('renders correctly', () => {
const wrapper = mount(MyComponent);
expect(wrapper.text()).toContain('Expected text');
});
```
2. **Mock External Dependencies**:
```js
import { mockNuxtImport } from '@nuxt/test-utils/runtime';
mockNuxtImport('useAsyncData', () => {
return () => ({
data: ref({
/* mock data */
}),
pending: ref(false),
});
});
```
3. **Test Server Routes Separately**:
```js
import { setup } from '@nuxt/test-utils/runtime';
import { describe, it, expect } from 'vitest';
describe('API endpoints', () => {
beforeEach(async () => {
await setup({
server: true,
});
});
it('returns users correctly', async () => {
const response = await fetch('/api/users');
const data = await response.json();
expect(data).toHaveLength(2);
});
});
```
## Security
1. **Never Trust Client Input**:
- Validate all inputs on the server
- Use `defineModel` with validators for form inputs
- Sanitize user-generated content before displaying
2. **Use HTTPS in Production**:
- Configure your hosting environment to use HTTPS
- Set proper security headers
3. **Implement CSRF Protection**:
- Use SameSite cookies
- Add CSRF tokens for sensitive operations
4. **Secure API Routes**:
- Implement proper authentication
- Add rate limiting for sensitive routes
- Use CORS correctly
## SEO Optimization
1. **Optimize Meta Tags**:
```js
<script setup>
useHead({
title: 'Page Title',
meta: [
{
name: 'description',
content: 'Page description'
},
{
property: 'og:title',
content: 'Open Graph Title'
}
]
})
</script>
```
2. **Use Semantic HTML**:
- Proper heading hierarchy
- Accessible landmarks
- Descriptive alt texts for images
3. **Implement Structured Data**:
- Add JSON-LD for rich snippets
- Use appropriate schemas for your content
## Deployment & Build
1. **Optimize Assets**:
- Enable image optimization
- Use webp format when possible
- Lazy load offscreen images
2. **Configure Caching Strategy**:
- Static assets: long cache
- API responses: appropriate TTL
- HTML: short or no cache
3. **Use CDN for Assets**:
- Configure your deployment to use CDN
- Set proper cache headers
4. **Monitor Performance**:
- Use Lighthouse in CI/CD
- Implement real user monitoring