vue-best-practices
π―Skillfrom dedalus-erp-pas/foundation-skills
|Provides comprehensive Vue.js 3 best practices guidelines for writing idiomatic, maintainable code using Composition API, Tailwind CSS, and PrimeVue.
Part of
dedalus-erp-pas/foundation-skills(21 items)
Installation
npx add-skill Dedalus-ERP-PAS/foundation-skills -g -ySkill Details
Vue.js 3 best practices guidelines covering Composition API, component design, reactivity patterns, Tailwind CSS utility-first styling, PrimeVue component library integration, and code organization. This skill should be used when writing, reviewing, or refactoring Vue.js code to ensure idiomatic patterns and maintainable code.
PrimeVue Best Practices
PrimeVue is a comprehensive Vue UI component library with 90+ components. Follow these patterns for effective integration and customization.
Installation & Setup
Correct: PrimeVue v4 setup with Vue 3
```typescript
// main.ts
import { createApp } from 'vue'
import PrimeVue from 'primevue/config'
import Aura from '@primevue/themes/aura'
import App from './App.vue'
const app = createApp(App)
app.use(PrimeVue, {
theme: {
preset: Aura,
options: {
darkModeSelector: '.dark-mode'
}
}
})
app.mount('#app')
```
Correct: Component registration (tree-shakeable)
```typescript
// main.ts - Register only components you use
import Button from 'primevue/button'
import DataTable from 'primevue/datatable'
import Column from 'primevue/column'
app.component('Button', Button)
app.component('DataTable', DataTable)
app.component('Column', Column)
```
PassThrough (PT) API
The PassThrough API allows customization of internal DOM elements without modifying component source:
Correct: Component-level PassThrough
```vue
header="User Profile"
toggleable
:pt="{
header: {
class: 'bg-primary-100 dark:bg-primary-900'
},
content: {
class: 'p-6'
},
title: {
class: 'text-xl font-semibold'
},
toggler: {
class: 'hover:bg-primary-200 dark:hover:bg-primary-800 rounded-full'
}
}"
>
Panel content here
```
Correct: Dynamic PassThrough with state
```vue
header="Collapsible Panel"
toggleable
:pt="{
header: (options) => ({
class: [
'transition-colors duration-200',
{
'bg-primary-500 text-white': options.state.d_collapsed,
'bg-surface-100 dark:bg-surface-800': !options.state.d_collapsed
}
]
})
}"
>
Content changes header style when collapsed
```
Global PassThrough Configuration
Define shared styles at the application level:
Correct: Global PT configuration
```typescript
// main.ts
import PrimeVue from 'primevue/config'
import Aura from '@primevue/themes/aura'
app.use(PrimeVue, {
theme: {
preset: Aura
},
pt: {
// All buttons get consistent styling
button: {
root: {
class: 'rounded-lg font-medium transition-all duration-200'
}
},
// All inputs get consistent styling
inputtext: {
root: {
class: 'rounded-lg border-2 focus:ring-2 focus:ring-primary-500'
}
},
// All panels share styling
panel: {
header: {
class: 'bg-surface-50 dark:bg-surface-900'
}
},
// Global CSS injection
global: {
css: `
.p-component {
font-family: 'Inter', sans-serif;
}
`
}
}
})
```
usePassThrough Utility
Extend existing presets with custom modifications:
Correct: Extending Tailwind preset
```typescript
// presets/custom-tailwind.ts
import { usePassThrough } from 'primevue/passthrough'
import Tailwind from 'primevue/passthrough/tailwind'
export const CustomTailwind = usePassThrough(
Tailwind,
{
panel: {
header: {
class: ['bg-gradient-to-r from-primary-500 to-primary-600']
},
title: {
class: ['text-white font-bold']
}
},
button: {
root: {
class: ['shadow-lg hover:shadow-xl transition-shadow']
}
}
},
{
mergeSections: true, // Keep original sections
mergeProps: false // Replace props (don't merge arrays)
}
)
```
Merge Strategy Reference:
| mergeSections | mergeProps | Behavior |
|---------------|------------|----------|
| true | false | Custom value replaces original (default) |
| true | true | Custom values merge with original |
| false | true | Only custom sections included |
| false | false | Minimal - only custom sections, no merging |
Unstyled Mode with Tailwind
Use unstyled PrimeVue components with full Tailwind control:
Correct: Unstyled mode configuration
```typescript
// main.ts
import PrimeVue from 'primevue/config'
app.use(PrimeVue, {
unstyled: true // Remove all default styles
})
```
Correct: Custom styled button with unstyled mode
```vue
label="Submit"
:pt="{
root: {
class: [
'inline-flex items-center justify-center',
'px-4 py-2 rounded-lg font-medium',
'bg-primary-600 text-white',
'hover:bg-primary-700 active:bg-primary-800',
'focus:outline-none focus:ring-2 focus:ring-primary-500 focus:ring-offset-2',
'transition-colors duration-150',
'disabled:opacity-50 disabled:cursor-not-allowed'
]
},
label: {
class: 'font-medium'
},
icon: {
class: 'mr-2'
}
}"
:ptOptions="{ mergeSections: false, mergeProps: false }"
/>
```
Wrapper Components Pattern
Create reusable wrapper components for consistent styling:
Correct: Button wrapper component
```vue
v-bind="$attrs"
:loading="loading"
:pt="{
root: {
class: [
'inline-flex items-center justify-center rounded-lg font-medium',
'transition-all duration-200',
'focus:outline-none focus:ring-2 focus:ring-offset-2',
'disabled:opacity-50 disabled:cursor-not-allowed',
variantClasses[variant],
sizeClasses[size]
]
}
}"
:ptOptions="{ mergeSections: false, mergeProps: false }"
>
```
Usage:
```vue
Submit Form
Cancel
```
DataTable Best Practices
Correct: Typed DataTable with Composition API
```vue
v-model:selection="selectedUsers"
:value="users"
:loading="loading"
:paginator="true"
:rows="rows"
:first="first"
:sortField="sortField"
:sortOrder="sortOrder"
dataKey="id"
stripedRows
removableSort
@page="(e) => first = e.first"
@sort="(e) => { sortField = e.sortField; sortOrder = e.sortOrder }"
>
:class="[
'px-2 py-1 rounded-full text-xs font-medium',
data.status === 'active'
? 'bg-green-100 text-green-800'
: 'bg-red-100 text-red-800'
]"
>
{{ data.status }}
```
Form Components Pattern
Correct: Form with validation using PrimeVue
```vue
id="email" v-model="formData.email" :class="{ 'p-invalid': errors.email }" aria-describedby="email-error" /> {{ errors.email }}
id="password" v-model="formData.password" :class="{ 'p-invalid': errors.password }" toggleMask :feedback="false" aria-describedby="password-error" /> {{ errors.password }}
id="role" v-model="formData.role" :options="roles" optionLabel="label" optionValue="value" placeholder="Select a role" :class="{ 'p-invalid': errors.role }" aria-describedby="role-error" /> {{ errors.role }}
```
Dialog & Overlay Patterns
Correct: Confirmation dialog with composable
```typescript
// composables/useConfirmDialog.ts
import { useConfirm } from 'primevue/useconfirm'
export function useConfirmDialog() {
const confirm = useConfirm()
function confirmDelete(
message: string,
onAccept: () => void,
onReject?: () => void
) {
confirm.require({
message,
header: 'Confirm Delete',
icon: 'pi pi-exclamation-triangle',
rejectClass: 'p-button-secondary p-button-outlined',
acceptClass: 'p-button-danger',
rejectLabel: 'Cancel',
acceptLabel: 'Delete',
accept: onAccept,
reject: onReject
})
}
function confirmAction(options: {
message: string
header: string
onAccept: () => void
onReject?: () => void
}) {
confirm.require({
message: options.message,
header: options.header,
icon: 'pi pi-info-circle',
rejectClass: 'p-button-secondary p-button-outlined',
acceptClass: 'p-button-primary',
accept: options.onAccept,
reject: options.onReject
})
}
return {
confirmDelete,
confirmAction
}
}
```
Usage:
```vue
```
Toast Notifications
Correct: Toast service with composable
```typescript
// composables/useNotifications.ts
import { useToast } from 'primevue/usetoast'
export function useNotifications() {
const toast = useToast()
function success(summary: string, detail?: string) {
toast.add({
severity: 'success',
summary,
detail,
life: 3000
})
}
function error(summary: string, detail?: string) {
toast.add({
severity: 'error',
summary,
detail,
life: 5000
})
}
function warn(summary: string, detail?: string) {
toast.add({
severity: 'warn',
summary,
detail,
life: 4000
})
}
function info(summary: string, detail?: string) {
toast.add({
severity: 'info',
summary,
detail,
life: 3000
})
}
return { success, error, warn, info }
}
```
Accessibility Best Practices
PrimeVue components are WCAG 2.0 compliant. Ensure proper usage:
Correct: Accessible form fields
```vue
{{ label }} :id="id" v-model="modelValue" :aria-required="required" :aria-invalid="!!error" :aria-describedby="error ? /> v-if="error" :id=" class="text-red-500" role="alert" > {{ error }} ${id}-error : undefined"${id}-error"
```
Lazy Loading Components
Correct: Async component loading for large PrimeVue components
```typescript
// components/lazy/index.ts
import { defineAsyncComponent } from 'vue'
export const LazyDataTable = defineAsyncComponent({
loader: () => import('primevue/datatable'),
loadingComponent: () => import('@/components/ui/TableSkeleton.vue'),
delay: 200
})
export const LazyEditor = defineAsyncComponent({
loader: () => import('primevue/editor'),
loadingComponent: () => import('@/components/ui/EditorSkeleton.vue'),
delay: 200
})
export const LazyChart = defineAsyncComponent({
loader: () => import('primevue/chart'),
loadingComponent: () => import('@/components/ui/ChartSkeleton.vue'),
delay: 200
})
```
Anti-Patterns to Avoid
Don't Mutate Props
Incorrect:
```vue
```
Correct:
```vue
```
Don't Use v-if with v-for
Incorrect:
```vue
{{ item.name }}
```
Correct:
```vue
{{ item.name }}
```
Don't Store Derived State
Incorrect:
```vue
```
Correct:
```vue
```
Don't Destructure Reactive Objects
Incorrect:
```vue
```
Correct:
```vue
```
Don't Concatenate Tailwind Class Names
Dynamic class concatenation breaks Tailwind's compiler and classes get purged in production:
Incorrect:
```vue
Content
```
Correct:
```vue
Content
```
Don't Overuse @apply
Excessive @apply usage defeats the purpose of utility-first CSS:
Incorrect:
```css
/ styles.css /
.card {
@apply mx-auto max-w-md rounded-xl bg-white p-6 shadow-lg;
}
.card-title {
@apply text-xl font-semibold text-gray-900;
}
.card-description {
@apply mt-2 text-gray-600;
}
.card-button {
@apply mt-4 rounded-md bg-blue-600 px-4 py-2 text-white hover:bg-blue-700;
}
```
Correct: Use Vue components instead
```vue
```
Don't Use Conflicting Utilities
Applying multiple utilities that target the same CSS property causes unpredictable results:
Incorrect:
```vue
```
Correct:
```vue
```
Don't Ignore Accessibility
Always include proper accessibility attributes alongside visual styling:
Incorrect:
```vue
```
Correct:
```vue
class="rounded bg-blue-600 p-2 text-white focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2"
aria-label="Close dialog"
>
```
Don't Create Overly Long Class Strings
Break down complex class combinations into logical groups or components:
Incorrect:
```vue
```
Correct: Extract to component or use computed
```vue
```
Don't Override PrimeVue Styles with CSS
Using CSS overrides bypasses the design system and causes maintenance issues:
Incorrect:
```css
/ styles.css - Avoid this approach /
.p-button {
background-color: #3b82f6 !important;
border-radius: 8px !important;
}
.p-datatable .p-datatable-thead > tr > th {
background: #f3f4f6 !important;
}
```
Correct: Use design tokens or PassThrough
```typescript
// main.ts - Use design tokens
app.use(PrimeVue, {
theme: {
preset: Aura,
options: {
cssLayer: {
name: 'primevue',
order: 'tailwind-base, primevue, tailwind-utilities'
}
}
},
pt: {
button: {
root: { class: 'rounded-lg' }
}
}
})
```
Don't Import Entire PrimeVue Library
Importing everything bloats bundle size:
Incorrect:
```typescript
// main.ts - Don't do this
import PrimeVue from 'primevue/config'
import * as PrimeVueComponents from 'primevue' // Imports everything!
Object.entries(PrimeVueComponents).forEach(([name, component]) => {
app.component(name, component)
})
```
Correct: Import only what you need
```typescript
// main.ts - Tree-shakeable imports
import Button from 'primevue/button'
import DataTable from 'primevue/datatable'
import Column from 'primevue/column'
app.component('Button', Button)
app.component('DataTable', DataTable)
app.component('Column', Column)
```
Don't Mix Styled and Unstyled Inconsistently
Mixing modes creates visual inconsistency:
Incorrect:
```typescript
// main.ts
app.use(PrimeVue, {
unstyled: true // Global unstyled
})
// SomeComponent.vue - Using styled component anyway
// No styles applied, looks broken
```
Correct: Choose one approach consistently
```typescript
// Option 1: Styled mode with PT customization
app.use(PrimeVue, {
theme: { preset: Aura },
pt: { / global customizations / }
})
// Option 2: Unstyled mode with complete PT styling
app.use(PrimeVue, {
unstyled: true,
pt: {
button: {
root: { class: 'px-4 py-2 bg-primary-600 text-white rounded-lg' }
}
// ... complete styling for all components
}
})
```
Don't Ignore Accessibility Attributes
PrimeVue provides accessibility out of the box, don't disable or ignore it:
Incorrect:
```vue
Invalid email
```
Correct: Maintain accessibility
```vue
icon="pi pi-trash"
aria-label="Delete item"
@click="deleteItem"
/>
id="email" v-model="email" :class="{ 'p-invalid': hasError }" :aria-invalid="hasError" aria-describedby="email-error" /> Invalid email
```
Don't Hardcode PassThrough in Every Component
Repeating PT configuration across components creates duplication:
Incorrect:
```vue
```
Correct: Use global PT or wrapper components
```typescript
// main.ts - Global configuration
app.use(PrimeVue, {
pt: {
button: {
root: { class: 'rounded-lg shadow-md' }
}
}
})
// Or use wrapper components (see Wrapper Components Pattern above)
```
Nuxt.js Specific Guidelines
When using Nuxt.js, follow these additional patterns:
- Auto-imports: Leverage Nuxt's auto-imports for Vue APIs and composables
- useFetch/useAsyncData: Use Nuxt's data fetching composables for SSR-compatible data loading
- definePageMeta: Use for page-level metadata and middleware
- Server routes: Use
server/api/for API endpoints - Runtime config: Use
useRuntimeConfig()for environment variables
References
Vue.js
- [Vue.js Documentation](https://vuejs.org)
- [Vue.js Style Guide](https://vuejs.org/style-guide/)
- [Composition API FAQ](https://vuejs.org/guide/extras/composition-api-faq.html)
- [VueUse - Collection of Vue Composition Utilities](https://vueuse.org)
- [Nuxt Documentation](https://nuxt.com)
- [Pinia Documentation](https://pinia.vuejs.org)
Tailwind CSS
- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
- [Styling with Utility Classes](https://tailwindcss.com/docs/styling-with-utility-classes)
- [Tailwind CSS v4 Release](https://tailwindcss.com/blog/tailwindcss-v4)
- [Class Variance Authority (CVA)](https://cva.style/docs)
- [tailwind-merge](https://github.com/dcastil/tailwind-merge)
- [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss)
- [Vue School - Tailwind CSS Fundamentals](https://vueschool.io/cour
More from this repository10
Guides developers in writing high-performance, modern React and Next.js applications by providing best practices for component architecture, performance, and UI design.
gitlab code review skill from dedalus-erp-pas/foundation-skills
postgres skill from dedalus-erp-pas/foundation-skills
article-extractor skill from dedalus-erp-pas/foundation-skills
Crafts distinctive, production-grade frontend interfaces with exceptional design quality, generating creative and polished web components and UI layouts.
Generates customized design system rules to automate Figma-to-code workflows, ensuring consistent UI/UX conventions and patterns across design and development teams.
Generates professional, user-friendly changelogs by automatically transforming git commits into clear, categorized release notes.
Performs comprehensive web UI review by analyzing code, accessibility, and design against industry guidelines with auto-fix capabilities.
Automates web testing and browser interactions using Playwright, enabling comprehensive website validation, form testing, and dynamic web application debugging.
Builds high-quality MCP servers that enable LLMs to interact with external services through well-designed, discoverable, and context-aware tools.