Padrões e Melhores Práticas do Vue.js

Guia abrangente para desenvolvimento Vue.js 3 usando Composition API (<script setup>), cobrindo design de componentes, reatividade, gerenciamento de estado, roteamento, testes e padrões SSR. Orientação específica para Nuxt é incluída onde difere do Vue puro.

Quando Ativar

Ative esta habilidade quando:

• O projeto usa Vue.js (qualquer versão), Nuxt, Vite + Vue ou Pinia.
• O usuário pergunta sobre arquitetura de componentes Vue, composables, reatividade ou gerenciamento de estado.
• Revisando Componentes de Arquivo Único Vue (arquivos .vue).
• Configurando Vue Router, stores Pinia ou configuração Vite/Vitest.
• Discutindo padrões específicos de desempenho, segurança ou SSR do Vue.

1. Estrutura do Projeto

Layout Recomendado (Orientado a Funcionalidades)

src/
├── api/              # API client and endpoint definitions
├── assets/           # Static assets (images, fonts, icons)
├── components/       # Shared/reusable components
│   ├── base/         # Base UI primitives (Button, Input, Modal)
│   └── features/     # Feature-specific shared components
├── composables/      # Reusable Composition API logic
├── layouts/          # Page layouts (optional)
├── pages/            # Route-level page components
├── router/           # Vue Router configuration
├── stores/           # Pinia stores
├── types/            # TypeScript type definitions
├── utils/            # Pure utility functions
└── App.vue           # Root component

Nomenclatura de Arquivos

2. Arquitetura de Componentes

Ordem do Componente de Arquivo Único

<script setup lang="ts">
// 1. Imports (vue → ecosystem → absolute → relative)
// 2. Props & Emits & Slots
// 3. Composables
// 4. Local state (ref/reactive)
// 5. Computed properties
// 6. Methods
// 7. Watchers
// 8. Lifecycle hooks
</script>

<template>
  <!-- Template content -->
</template>

<style scoped>
  /* Scoped styles */
</style>

Apresentacional vs. Container

• Componentes Container: Possuem busca de dados, estado e efeitos colaterais. Renderizam componentes apresentacionais.
• Componentes Apresentacionais: Recebem props, emitem eventos. Sem chamadas de API, sem acesso a store. Renderização pura.

Melhores Práticas de Props

// Type-based props with defaults
interface Props {
  label: string;
  variant?: "primary" | "secondary";
  disabled?: boolean;
  items: Item[];
}

const props = withDefaults(defineProps<Props>(), {
  variant: "primary",
  disabled: false,
});

• Sempre forneça type, e required/default onde apropriado.
• Props booleanas: isXxx, hasXxx, canXxx.
• Nunca modifique props — emita eventos em vez disso.
• Para vinculação v-model, use defineModel() (Vue 3.4+) ou modelValue + update:modelValue.

Eventos

const emit = defineEmits<{
  submit: [];
  "update:modelValue": [value: string];
  select: [id: string, index: number];
}>();

• Use kebab-case em templates (@update:model-value).
• Use camelCase em script (emit("update:modelValue", val)).

3. Composables (Lógica Reutilizável)

Estrutura

// composables/useDebounce.ts
export function useDebounce<T>(value: MaybeRef<T>, delay: number): Ref<T> {
  const debounced = ref(toValue(value)) as Ref<T>;

  let timer: ReturnType<typeof setTimeout>;
  watch(
    () => toValue(value),
    (newVal) => {
      clearTimeout(timer);
      timer = setTimeout(() => { debounced.value = newVal; }, delay);
    }
  );

  onUnmounted(() => clearTimeout(timer));
  return readonly(debounced);
}

Regras

• Deve começar com o prefixo use.
• Retorne valores reativos (ref, computed, reactive), nunca primitivos simples.
• Aceite entradas reativas via MaybeRef / toRef() / toValue().
• Limpe efeitos colaterais em onUnmounted ou watcher onCleanup.
• Sem efeitos colaterais no escopo do módulo.

vs. Mixins

Composables substituem completamente os mixins do Vue 2:

• Mixins: Fluxo de dados opaco, colisões de fonte de verdade, conflitos de nome.
• Composables: Importações explícitas, valores de retorno claros, composable e "tree-shakable".

4. Gerenciamento de Estado

Quando Usar o Quê

…