Vue 3 FSD Development

Guidelines para desenvolvimento Vue 3 seguindo arquitetura Feature-Sliced Design (FSD) adaptada.

Princípios Fundamentais

1. Separação de Responsabilidades: Cada camada tem responsabilidade única e bem definida
2. Isolamento de Features: Features são auto-contidas e independentes
3. Reutilização Inteligente: Widgets e shared para código reutilizável
4. Performance First: Lazy loading e code splitting por padrão
5. Type Safety: TypeScript em todos os arquivos

Arquitetura FSD

Estrutura de camadas (ordem de dependência):

app/ → pages/ → features/ → widgets/ → shared/

Regras de dependência:

• app/ não depende de nenhuma camada
• pages/ pode importar de features/, widgets/, shared/
• features/ pode importar de widgets/, shared/
• widgets/ pode importar de shared/
• shared/ não depende de outras camadas

NUNCA:

• ❌ Features importando de pages/
• ❌ Widgets importando de features/ ou pages/
• ❌ Shared importando de qualquer outra camada

Para detalhes completos, veja architecture.md.

Estrutura de Features

Cada feature segue esta estrutura:

features/[feature-name]/
├── index.vue              # Componente principal
├── model/                 # Lógica de negócio
│   ├── [feature]Schema.ts # Schema Zod
│   └── use[Feature].ts    # Composable
├── ui/                    # Componentes UI específicos
│   └── [component]/
│       ├── index.vue
│       └── __tests__/
└── store/                 # Store Pinia (se necessário)

Diretrizes:

• Uma feature = um domínio de negócio
• Lógica sempre em model/
• UI específica em ui/
• Testes junto ao código em __tests__/

Lazy Loading Obrigatório

Rotas: Sempre usar dynamic imports:

component: () => import('@/pages/users/UsersView.vue')

Features pesadas: Lazy load quando possível:

<script setup>
const HeavyComponent = defineAsyncComponent(() => 
  import('@/features/heavy-feature/index.vue')
)
</script>

Mocks condicionais: Lazy load de MSW:

if (import.meta.env.VITE_ENABLE_MOCK_SERVER === 'true') {
  const { worker } = await import('../shared/mocks/browser.ts')
  worker.start()
}

Para otimizações avançadas, veja performance.md.

Padrões de Código

Composables com Vue Query

import { useMutation } from '@tanstack/vue-query'
import { toast } from 'vue-sonner'
import { postLogin as postLoginService } from '@/shared/api/auth-api/postLogin'
import type { Payload } from '@/shared/api/auth-api/types/postLogin.types'

const postLogin = () => {
  const { isPending, isError, error, isSuccess, mutate } = useMutation({
    mutationFn: (payload: Payload) =>
      postLoginService(payload).catch((error) =>
        toast.error(error?.response?.data?.message || 'Erro desconhecido.'),
      ),
  })

  return { isPending, isError, error, isSuccess, mutate }
}

export function useLogin() {
  return { postLogin }
}

APIs

import { axiosClient } from '../config/http-client'
import type { Payload, Response } from './types/postLogin.types'

export async function postLogin(payload: Payload): Promise<Response> {
  const response = await axiosClient.request<Response>({
    endpoint: 'login',
    method: 'POST',
    body: payload,
  })
  return response.data
}

Validação Zod

import { z } from 'zod'

const loginSchema = z.object({
  email: z.string().email('Email inválido'),
  password: z.string().min(6, 'Senha deve ter no mínimo 6 caracteres'),
})

export type LoginFormData = z.infer<typeof loginSchema>

Para mais padrões, veja patterns.md.

Boas Práticas

✅ FAZER

• Usar Composition API com <script setup>
• Tipar tudo com TypeScript
• Separar tipos em arquivos types/
• Usar cn() para merge de classes Tailwind
• Implementar error handling em composables
• Usar Vue Query para estado servidor
• Usar Pinia apenas para estado cliente global
• Testar features junto com o código

❌ NÃO FAZER

• Misturar lógica de negócio com UI
• Criar dependências circulares entre camadas
• Importar features em widgets
• Usar any em TypeScript
• Hardcode de valores (usar env vars)
• Lógica complexa em templates
• Mutar props diretamente
• Criar stores Pinia para estado local

Para lista completa, veja best-practices.md.

Performance

Code Splitting

• Rotas sempre lazy loaded
• Features pesadas com defineAsyncComponent
• Bibliotecas grandes importadas dinamicamente

Vue Query

• Configurar staleTime e gcTime apropriadamente
• Usar queryKey reativo para invalidação automática
• Implementar paginação com currentPage e perPage

Renderização

• Usar v-show para toggle frequente
• Usar v-if para renderização condicional pesada
• Evitar watchers desnecessários
• Usar computed para valores derivados

Para otimizações avançadas, veja performance.md.

Nomenclatura

• Componentes: PascalCase (LoginView.vue, UserDialog.vue)
• Composables: camelCase com use (useLogin.ts, useListUsers.ts)
• Stores: camelCase com use (useAuthStore)
• APIs: camelCase com verbo (postLogin.ts, getAllUsers.ts)
• Features: kebab-case (login-auth/, handle-users/)
• Tipos: PascalCase (Payload, Response, User)

Imports

• Sempre usar alias @/ para src/
• Ordenação automática via ESLint simple-import-sort
• Agrupar: externos → internos → tipos

import { useMutation } from '@tanstack/vue-query'
import { toast } from 'vue-sonner'

import { postLogin as postLoginService } from '@/shared/api/auth-api/postLogin'
import type { Payload } from '@/shared/api/auth-api/types/postLogin.types'

Recursos Adicionais

• architecture.md - Detalhes sobre FSD e estrutura
• best-practices.md - Boas práticas e anti-patterns
• performance.md - Lazy loading e otimizações
• patterns.md - Padrões de código específicos