DEV Community: Gabriel Caiana

Composable Abstraction Layer: o pattern que faltava entre Pinia e seus componentes Vue

Gabriel Caiana — Tue, 26 May 2026 00:58:54 +0000

Nos últimos anos, trabalhei com arquiteturas frontend em diferentes escalas — desde projetos pequenos com um punhado de componentes até aplicações grandes, com múltiplos squads contribuindo no mesmo repositório. Passei por fases de Vuex, migrei para Pinia, experimentei patterns como Repository Pattern adaptado para o frontend, criei abstrações demais, abstrações de menos, e quebrei a cara com todas as combinações possíveis.

O que vou apresentar aqui não é uma ideia que surgiu de um artigo ou de uma spec. É um padrão que emergiu da prática — de ver os mesmos problemas se repetirem em projetos Vue 3 + Nuxt conforme eles cresciam, e de ir ajustando a arquitetura até chegar em algo que realmente funciona no dia a dia. Chamo de Composable Abstraction Layer (CAL).

A ideia é simples: inserir uma camada de composables entre suas stores Pinia e seus componentes Vue, eliminando acoplamento, centralizando lógica e tornando cada camada testável de forma independente. Parece óbvio quando você lê, mas a maioria dos projetos que encontro por aí não faz isso — e paga o preço conforme escala.

O problema

Vou usar um cenário que todo mundo que trabalha com e-commerce conhece: uma página de produto. O componente precisa buscar dados, armazená-los, exibir loading, tratar erros e expor ações. A abordagem mais intuitiva com Pinia:

<script setup lang="ts">
const store = useProductStore();

await store.fetchProduct(route.params.slug);

const product = computed(() => store.product);
const loading = computed(() => store.loading);
</script>

<template>
  <div v-if="loading">Carregando...</div>
  <div v-else>{{ product.name }}</div>
</template>

Parece razoável. E funciona — eu mesmo escrevi muito código assim. Mas agora multiplique isso por 40 componentes, 8 stores e 3 squads contribuindo no mesmo repositório. É aí que as coisas começam a desmoronar.

O que começa a dar errado

1. Acoplamento estrutural

Todo componente conhece a API interna da store: nomes de state, getters, actions. Renomear store.product para store.currentProduct exige alterar dezenas de arquivos .vue. Já vi refactors simples virarem PRs monstruosos por causa disso.

2. Lógica de fetch espalhada

Alguns componentes chamam store.fetchProduct(). Outros assumem que a store já está populada. Outros duplicam a chamada "por segurança". Não há um ponto único que orquestre o fetch e a sincronização do estado.

<!-- ComponenteA.vue -->
<script setup>
const store = useProductStore();
await store.fetchProduct(slug); // faz o fetch
</script>

<!-- ComponenteB.vue -->
<script setup>
const store = useProductStore();
// assume que já foi feito fetch — mas será que foi?
const name = store.productName;
</script>

Esse tipo de inconsistência é silenciosa. Funciona em dev, funciona no caminho feliz, e quebra em produção quando a ordem de montagem dos componentes muda.

3. Testes acoplados ao Pinia

Para testar qualquer componente, é necessário configurar Pinia, criar a store, popular o estado inicial e mockar actions. O setup de teste de um componente simples vira um ritual:

// Setup de teste acoplado
const pinia = createPinia();
setActivePinia(pinia);
const store = useProductStore();
store.$patch({ product: mockProduct, loading: false });

const wrapper = mount(ProductCard, {
  global: { plugins: [pinia] },
  props: { slug: 'racao-premium' },
});

Quando o setup do teste é mais longo que o teste em si, algo está errado.

4. Side-effects sem dono

Error tracking, analytics, notificações — tudo acaba nos componentes. Cada dev resolve de um jeito, em um lugar diferente. Já perdi horas rastreando por que um evento de analytics disparava duas vezes — era porque dois componentes diferentes tinham a mesma lógica copiada.

5. Reatividade frágil

Desestruturar diretamente da store perde reatividade. Devs precisam lembrar de usar storeToRefs — e inevitavelmente esquecem:

// Perde reatividade silenciosamente
const { product, loading } = useProductStore();

// Funciona, mas exige conhecimento específico do Pinia
const { product, loading } = storeToRefs(useProductStore());

Esse é o tipo de bug que não aparece em teste, não aparece em dev com dados estáticos, e aparece em produção quando o usuário navega entre páginas e o estado muda.

O resultado é um codebase onde a camada de UI sabe demais sobre gerenciamento de estado, e qualquer mudança na store tem blast radius imprevisível.

A motivação

Quando o Vue 3 trouxe a Composition API e com ela os composables — funções que encapsulam lógica reativa e reutilizável — o ecossistema rapidamente os adotou para lógica de UI (useMediaQuery, useDebounceFn), mas a maioria dos projetos parou aí.

A pergunta que me levou ao CAL foi simples:

Se composables já são o padrão para abstrair lógica reativa, por que a camada de estado — a parte mais crítica da aplicação — ainda é acessada diretamente?

A resposta é que não precisaria ser. Composables podem servir como contrato de API entre o estado da aplicação e a UI, exatamente como um controller serve de contrato entre o model e a view em arquiteturas MVC. A diferença é que, no Vue 3, a ferramenta já está na linguagem — não precisa de framework adicional.

Depois de testar variações desse pattern em projetos de complexidades diferentes, cheguei em cinco princípios que guiam a implementação:

Encapsulamento: componentes não sabem que Pinia existe
Separação de responsabilidades: Store (estado) → Composable (lógica) → Componente (UI)
Contrato estável: o composable define a API pública; a implementação interna pode mudar
Testabilidade em camadas: cada camada pode ser testada isoladamente
Reatividade garantida: composables retornam computed() — sem armadilhas de desestruturação

A solução: Composable Abstraction Layer

Arquitetura

┌──────────────────────────────────────┐
│          COMPONENTES (UI)            │   ← Só consomem composables
│  ┌──────────────────────────────────┐│
│  │      COMPOSABLES (LÓGICA)        ││   ← Consomem stores + APIs, expõem API limpa
│  │  ┌──────────────────────────────┐││
│  │  │       STORES (ESTADO)        │││   ← Estado reativo puro + getters
│  │  └──────────────────────────────┘││
│  └──────────────────────────────────┘│
└──────────────────────────────────────┘

A regra é uma só

Arquivos .vue (pages e components) nunca chamam useXxxStore(). Toda leitura de estado e toda ação passam por composables.

// ❌ Proibido em .vue
const store = useProductStore();
const product = store.product;

// ✅ Permitido em .vue
const { product, loading, error } = useProduct(slug);

Composables e código de infraestrutura (middlewares, plugins, server routes) podem acessar stores diretamente — eles são a camada que consome a store.

Parece restritivo? É. E é justamente essa restrição que dá poder ao pattern. Quando todo acesso ao estado passa por um funil, você ganha um ponto único de controle, cache, logging, transformação e evolução.

Implementação passo a passo

Vou mostrar como implementar o CAL do zero usando o cenário de página de produto. A mesma estrutura se aplica a qualquer feature.

Passo 1: Store como estado puro

A store não faz fetch, não tem side-effects. Ela é um container de estado reativo com getters computados. Pense nela como um "banco de dados local" — ela guarda dados e responde perguntas sobre eles.

// store/product.ts
import type { Product, ReviewSummary } from '@/types/api';

interface ProductState {
  product: Product | null;
  reviewSummary: ReviewSummary | null;
}

export const useProductStore = defineStore('product', {
  state: (): ProductState => ({
    product: null,
    reviewSummary: null,
  }),

  getters: {
    hasProduct: (state) => !!state.product,
    productName: (state) => state.product?.name ?? '',
    averageRating: (state) => state.reviewSummary?.ratingAvg ?? 0,
    totalReviews: (state) => state.reviewSummary?.reviewsCount ?? 0,
  },
});

A store não sabe de onde os dados vêm. Ela não importa $fetch, não chama APIs, não dispara notificações. Isso é proposital.

Passo 2: Composable como camada de abstração

O composable é onde tudo acontece: fetch, transformação, sincronização com a store e construção da API pública. Ele é o "backend-for-frontend" da sua feature.

// composables/useProduct.ts
import type { ProductResponse } from '@/types/api';

export function useProduct(slug: string) {
  const store = useProductStore();

  const { data, error, pending, refresh } = useLazyFetch<ProductResponse>(
    '/api/products',
    {
      key: `product-${slug}`,
      method: 'POST',
      body: { slug },
      transform: (response: ProductResponse) => {
        store.$patch((state) => {
          state.product = response.product ?? null;
          state.reviewSummary = response.reviewSummary ?? null;
        });
        return response;
      },
    }
  );

  return {
    // Dados — sempre computed() para garantir reatividade
    product: computed(() => store.product ?? data.value?.product),
    reviewSummary: computed(
      () => store.reviewSummary ?? data.value?.reviewSummary
    ),

    // Estado da requisição
    error,
    pending,
    refresh,

    // Getters derivados
    hasProduct: computed(() => store.hasProduct),
    productName: computed(() => store.productName),
    averageRating: computed(() => store.averageRating),
  };
}

Alguns detalhes que valem destaque:

$patch com callback: store.$patch((state) => { ... }) agrupa múltiplas atualizações em uma única notificação de reatividade. A forma com objeto literal (store.$patch({ key: value })) não tem o mesmo ganho e é menos type-safe. Parece um detalhe, mas em stores com muitos campos, faz diferença perceptível.
computed() em tudo que é reativo: o componente recebe refs computadas que rastreiam dependências automaticamente — sem risco de perder reatividade. Esse é um dos pontos que mais gosto no pattern: ele elimina uma classe inteira de bugs.
Fallback store.x ?? data.value?.x: garante que o dado está disponível tanto via store (se foi populada por outro composable ou por SSR) quanto via fetch direto.

Passo 3: Componente consome apenas o composable

<!-- pages/product/[slug].vue -->
<script setup lang="ts">
const route = useRoute();
const slug = route.params.slug as string;

const { product, pending, error, averageRating } = useProduct(slug);
</script>

<template>
  <div v-if="pending" class="product-skeleton">Carregando...</div>
  <div v-else-if="error" class="product-error">
    Não foi possível carregar o produto.
  </div>
  <div v-else-if="product" class="product-page">
    <h1 class="product-page__title">{{ product.name }}</h1>
    <ProductRating :average="averageRating" />
  </div>
</template>

O componente não sabe que Pinia existe. Ele não importa stores, não chama $patch, não faz fetch. Ele recebe dados reativos e renderiza. É assim que deveria ser.

Padrões que emergem

Conforme o CAL amadurece em um projeto, padrões recorrentes se consolidam. Na minha experiência, quatro se mostraram estáveis o suficiente para serem considerados "canônicos".

Padrão 1 — Composable de Leitura (Query)

O mais comum. Faz fetch, popula a store, expõe dados reativos. É o useProduct que mostrei acima, mas funciona para qualquer feature que precisa buscar dados:

export async function useFavorites() {
  const store = useFavoriteStore();
  const authStore = useAuthStore();

  const userId = computed(() => authStore.session?.id ?? '');

  const { data, error, refresh } = await useAsyncData('favorites', () =>
    fetchFavorites(userId.value)
  );

  watch(
    () => data.value?.items,
    (items) => {
      if (items) {
        store.$patch((state) => {
          state.items = items;
        });
      }
    },
    { immediate: true }
  );

  return {
    favorites: computed(() => store.items),
    hasFavorites: computed(() => store.items.length > 0),
    isEmpty: computed(() => store.items.length === 0),
    refresh,
    error,
  };
}

Note que o composable consome outra store (useAuthStore) para obter o userId. Isso é perfeitamente válido — composables são a camada que tem permissão para acessar stores. O componente nunca precisa saber que autenticação e favoritos estão relacionados internamente.

Padrão 2 — Composable de Ação (Mutation)

Encapsula uma operação de escrita. Gerencia pending e error internamente. Não precisa de store se o estado é efêmero — e na maioria dos casos de mutations, ele é.

export function useRemoveFromFavorites() {
  const pending = ref(false);
  const error = ref<Error | null>(null);

  async function remove(productIds: string[], onSuccess?: () => Promise<void>) {
    pending.value = true;
    error.value = null;

    try {
      await $fetch('/api/favorites/remove', {
        method: 'DELETE',
        body: { productIds },
      });
      await onSuccess?.();
    } catch (e) {
      error.value = e instanceof Error ? e : new Error(String(e));
      throw e;
    } finally {
      pending.value = false;
    }
  }

  return { remove, pending, error };
}

O detalhe interessante aqui é o onSuccess callback. Em vez de o composable de ação saber como atualizar a lista de favoritos (o que criaria acoplamento entre composables), ele aceita um callback genérico. Na prática, a page passa o refresh do composable de leitura:

<script setup lang="ts">
const { favorites, refresh } = await useFavorites();
const { remove, pending: removing } = useRemoveFromFavorites();

async function handleRemove(productId: string) {
  await remove([productId], refresh);
}
</script>

Essa composição é limpa e explícita. Cada composable tem uma responsabilidade, e o componente orquestra a interação entre eles.

Padrão 3 — Wrapper de Store Legada

Esse é o padrão que mais me salvou em migrações. Quando o projeto depende de stores que vieram de um pacote externo ou de um módulo legado, o composable atua como adapter:

// Store vem de pacote externo — não controlamos a API
// import { useSessionStore } from '@acme/auth-module'

export function useAuth() {
  const store = useSessionStore();

  return {
    isLoggedIn: computed(() => store.isLogged),
    user: computed(() => store.getSession),
    isSubscriber: computed(() => store.isClubMember ?? false),
  };
}

Isso é poderoso por dois motivos:

Se o pacote externo mudar a API da store (e isso acontece), apenas o composable precisa ser atualizado. Já passei por uma atualização de major version de um módulo de auth onde 100% da migração ficou contida em um único arquivo de composable. Zero mudanças em componentes.
Podemos normalizar nomenclatura — o componente nunca precisa saber que internamente o getter se chama getSession ou isLogged. A API que a UI consome é a que faz sentido para a UI.

Padrão 4 — Composable Utilitário

Funções que usam store internamente mas expõem uma API semântica de alto nível. O exemplo mais clássico são notificações:

export function useSuccessNotification(message: string) {
  useNotificationStore().show({
    message,
    type: 'positive',
  });
}

export function useErrorNotification(error: unknown, fallbackMessage?: string) {
  const normalized = error instanceof Error ? error : new Error(String(error));
  const message = fallbackMessage ?? extractMessage(normalized);

  useNotificationStore().show({
    message,
    type: 'negative',
  });

  // Centraliza error tracking
  useNuxtApp().$errorTracker?.notify(normalized, {
    context: { displayMessage: message },
  });
}

O componente não sabe como notificações funcionam internamente. Não sabe que existe um store por trás, nem que errors são enviados para um serviço de tracking:

try {
  await remove([product.id], refresh);
  useSuccessNotification('Produto removido dos favoritos');
} catch (error) {
  useErrorNotification(error, 'Falha ao remover. Tente novamente.');
}

Esse tipo de composable utilitário é onde o CAL brilha para centralizar side-effects que antes ficavam copiados em dezenas de componentes.

Organização de arquivos

O CAL se encaixa naturalmente em projetos Nuxt organizados por feature (layers). Se você ainda não está familiarizado com Nuxt Layers, o post Arquitetura Modular com Nuxt Layers em Projetos Vue é um bom ponto de partida — a estrutura abaixo faz ainda mais sentido com esse contexto.

layers/
├── favorites/
│   ├── store/
│   │   └── favorites.ts             # Estado puro + getters
│   ├── composables/
│   │   ├── useFavorites.ts          # Query principal
│   │   ├── useAddToFavorites.ts     # Mutation: adicionar
│   │   └── useRemoveFromFavorites.ts # Mutation: remover
│   ├── components/
│   │   ├── FavoriteCard.vue         # Consome via props (vindo da page)
│   │   └── FavoriteCard.test.ts
│   ├── pages/
│   │   └── favorites/
│   │       └── index.vue            # Consome composables
│   └── types/
│       └── favorites.ts             # Types derivados
├── product/
│   ├── store/
│   │   └── product.ts
│   ├── composables/
│   │   ├── useProduct.ts
│   │   ├── useReview.ts
│   │   └── useQuestion.ts
│   └── ...
└── shared/
    └── composables/
        ├── useAuth.ts               # Wrapper de store legada
        ├── useCart.ts               # Wrapper de store legada
        └── useNotification.ts       # Utilitários

Convenções de nomenclatura

Artefato	Padrão	Exemplo
Store	`use[Feature]Store`	`useFavoriteStore`
Composable principal	`use[Feature]`	`useFavorites`
Composable de ação	`use[Feature]Action`	`useRemoveFromFavorites`
Composable de filtro	`use[Feature]Filters`	`useProductFilters`

Uma coisa que aprendi: manter o composable e seu teste no mesmo diretório (colocation) faz toda a diferença. Quando o teste está ao lado do arquivo, a barreira para escrevê-lo diminui. Quando está em uma pasta __tests__ distante, ninguém lembra que ele existe.

Testabilidade

Essa é, honestamente, a vantagem que mais me convenceu a adotar o CAL de forma consistente. Cada camada é testável de forma isolada, e o setup de cada teste é proporcionalmente simples.

Testando o composable (unit test)

import { describe, it, expect, vi } from 'vitest';

// Mock do fetch — único ponto de integração
vi.mock('#app', () => ({
  useLazyFetch: vi.fn(() => ({
    data: ref({ product: { name: 'Ração Premium', slug: 'racao-premium' } }),
    error: ref(null),
    pending: ref(false),
    refresh: vi.fn(),
  })),
}));

describe('useProduct', () => {
  it('should return product data when fetch succeeds', () => {
    const { product, hasProduct, pending } = useProduct('racao-premium');

    expect(product.value).toEqual({
      name: 'Ração Premium',
      slug: 'racao-premium',
    });
    expect(hasProduct.value).toBe(true);
    expect(pending.value).toBe(false);
  });

  it('should expose error when fetch fails', () => {
    vi.mocked(useLazyFetch).mockReturnValueOnce({
      data: ref(null),
      error: ref(new Error('Network error')),
      pending: ref(false),
      refresh: vi.fn(),
    });

    const { error, hasProduct } = useProduct('slug-invalido');

    expect(error.value).toBeTruthy();
    expect(hasProduct.value).toBe(false);
  });
});

Testando o componente (component test)

Aqui é onde a mágica aparece. O componente não sabe que Pinia existe — basta mockar o composable:

import { mountSuspended } from '@nuxt/test-utils/runtime';

// Mock do composable — a store nem entra na equação
vi.mock('@/composables/useProduct', () => ({
  useProduct: vi.fn(() => ({
    product: computed(() => ({ name: 'Ração Premium' })),
    pending: ref(false),
    error: ref(null),
    hasProduct: computed(() => true),
    averageRating: computed(() => 4.5),
  })),
}));

describe('ProductPage', () => {
  it('should render product name', async () => {
    const wrapper = await mountSuspended(ProductPage, {
      route: { params: { slug: 'racao-premium' } },
    });

    expect(wrapper.text()).toContain('Ração Premium');
  });

  it('should render loading state', async () => {
    vi.mocked(useProduct).mockReturnValueOnce({
      product: computed(() => null),
      pending: ref(true),
      error: ref(null),
      hasProduct: computed(() => false),
      averageRating: computed(() => 0),
    });

    const wrapper = await mountSuspended(ProductPage, {
      route: { params: { slug: 'racao-premium' } },
    });

    expect(wrapper.text()).toContain('Carregando');
  });
});

Compare isso com o setup que mostrei no início do artigo, onde era necessário configurar Pinia, criar store, popular estado. Com CAL, o teste do componente mocka uma função que retorna refs — o mesmo contrato que o componente já usa em produção. É direto, é previsível, e encoraja o time a escrever mais testes.

Enforcement: como garantir a adoção

Documentar o padrão não é suficiente — aprendi isso da maneira difícil. Sem enforcement ativo, a erosão arquitetural é inevitável. Basta um dev com pressa acessar a store direto "só dessa vez" e, duas semanas depois, metade do time está fazendo o mesmo. Estas são as estratégias que funcionaram para mim:

1. Code review com checklist

Incluir na checklist de PR:

[ ] Nenhum arquivo .vue importa useXxxStore()
[ ] Composables usam $patch com callback (não object literal)
[ ] Dados reativos expostos via computed()

2. Auditoria automatizada

Um script de auditoria que faz grep por violações:

# Busca imports de store em arquivos .vue
grep -rn "useXxxStore\|use.*Store()" --include="*.vue" layers/

# Busca $patch com object literal (sem callback)
grep -rn '\$patch({' --include="*.ts" layers/

Pode parecer rudimentar, mas é surpreendentemente eficaz. Em um projeto onde apliquei isso, rodamos o script no CI e bloqueamos merge quando encontrava violações. Em três meses, o time inteiro internalizou o pattern.

3. Scaffolding que já nasce no padrão

Templates de geração de código que criam store + composable + componente já seguindo o CAL. Devs não precisam lembrar do padrão — o boilerplate já está correto. Isso reduz fricção de adoção drasticamente, principalmente para quem está chegando no projeto.

4. Testes como barreira

Se componentes só testam via composables mockados, qualquer tentativa de acessar store diretamente no componente vai falhar no teste — porque a store não está configurada. Os testes viram uma barreira natural contra violações.

Quando NÃO usar

Seria desonesto da minha parte apresentar o CAL como bala de prata. Ele adiciona uma camada de indireção, e isso tem custo. Ao longo dos projetos em que apliquei, fui refinando o entendimento de onde ele faz sentido e onde é overhead:

Projetos pequenos (< 5 stores, 1-2 devs): o overhead de manter composables intermediários pode não compensar. Se todo o time é você, o acoplamento é gerenciável.
Protótipos e MVPs: velocidade importa mais que arquitetura. Acessar store direto é mais rápido de escrever. Você sempre pode refatorar depois — se o projeto sobreviver.
Estado puramente local: se o estado só existe dentro de um componente (ref() local), não precisa de store nem de composable. Não crie abstrações para estado que ninguém mais consome.
Composable que só repassa: se o composable não adiciona lógica (sem fetch, sem transformação, sem side-effects) e apenas repassa storeToRefs, avalie se a indireção se justifica. Às vezes um storeToRefs direto é honestamente a melhor opção.

A regra de ouro que uso: adote o CAL quando múltiplos componentes consomem a mesma store ou quando a lógica de sincronização de estado é não-trivial. Na minha experiência, em qualquer projeto que tende a escalar — seja em features, em devs ou em complexidade de estado — esse threshold é atingido rápido.

Comparação: antes e depois

Antes (acesso direto)

ComponenteA.vue ──→ useProductStore()
ComponenteB.vue ──→ useProductStore()
ComponenteC.vue ──→ useProductStore()
PageX.vue ─────────→ useProductStore() + fetch + error handling
PageY.vue ─────────→ useProductStore() + fetch + error handling (duplicado)

5 pontos de acoplamento com a store
Lógica de fetch duplicada
Teste de cada componente exige setup de Pinia

Depois (CAL)

ComponenteA.vue ──→ props (dados vêm da page)
ComponenteB.vue ──→ props
ComponenteC.vue ──→ useProduct()
PageX.vue ─────────→ useProduct()
PageY.vue ─────────→ useProduct()
                          │
                    useProduct() ──→ useProductStore()

1 ponto de acoplamento com a store (o composable)
Lógica de fetch centralizada
Componentes testáveis com mock simples

Resumo

Camada	Responsabilidade	Acessa store?	Acessa composable?
Store	Estado reativo + getters puros	—	Não
Composable	Fetch, lógica, side-effects, API pública	Sim	Pode compor outros
Componente	Renderização + interação do usuário	Nunca	Sim
Infraestrutura (middleware, plugin)	Setup, guards, config	Sim	Pode usar ambos

O Composable Abstraction Layer não é um framework, não é uma lib, não exige dependências. É um padrão arquitetural — uma convenção sobre onde colocar cada tipo de lógica no ecossistema Vue 3 + Pinia. A Composition API já nos deu a ferramenta. O CAL é apenas a disciplina de usá-la como camada de abstração, e não só como repositório de funções utilitárias.

Cheguei nesse pattern depois de anos experimentando, errando e refinando. Não é perfeito, não é para todo projeto, mas em aplicações que tendem a escalar — em features, em devs, em complexidade — essa disciplina é a diferença entre um codebase que escala junto e um que só sobrevive.

Se você está em um projeto Vue 3 + Pinia que está crescendo e sente que o estado está virando um emaranhado, experimente aplicar o CAL em uma feature nova. Não precisa refatorar tudo de uma vez. Comece por uma store, crie o composable, ajuste os componentes. Quando o time sentir a diferença nos testes e nos refactors, a adoção acontece naturalmente.

Arquitetura Modular com Nuxt Layers em Projetos Vue

Gabriel Caiana — Thu, 02 Oct 2025 07:57:40 +0000

O Desafio Invisível que Todo Dev Frontend Enfrenta

Você conhece essa história: começou um projeto Vue pequeno, organizou tudo direitinho - components aqui, pages ali, stores no seu lugar. Três meses depois, você tem 147 componentes, e encontrar aquele ProductCardVariantB.vue virou uma expedição arqueológica.

Pior ainda: você precisa mexer no carrinho de compras, mas os arquivos estão espalhados em 7 pastas diferentes. Um componente aqui, uma store ali, as páginas em outro lugar... e aquela sensação de que a organização que fazia sentido no início agora está atrapalhando seu trabalho.

Este é o problema silencioso da escalabilidade em frontend. E a solução vem de um lugar inesperado: conceitos de arquitetura backend aplicados ao mundo do navegador.

A Inspiração: Monólitos Modulares do Backend

No mundo backend, existe um debate eterno: monólito ou microserviços? Mas arquitetos como Sam Newman e Simon Brown propuseram uma terceira via: o monólito modular.

Como Martin Fowler explica, um monólito modular é "uma aplicação única que mantém uma estrutura interna altamente modularizada". Você tem os benefícios de modularização (separação de responsabilidades, desenvolvimento independente, fronteiras claras) sem a complexidade operacional de microserviços (múltiplos deploys, comunicação via rede, orquestração).

O Princípio Fundamental

A sacada genial é organizar o código por domínio de negócio em vez de responsabilidade técnica. No backend, isso significa que tudo relacionado a "Pagamentos" fica junto - controllers, services, repositories, models. Tudo sobre "Usuários" em outro módulo. E assim por diante.

Mas... e no frontend?

O Problema da Organização Tradicional em Vue/Nuxt

Vamos ser honestos sobre como 99% dos projetos Vue são organizados hoje:

meu-ecommerce/
├── components/
│   ├── cart/
│   │   ├── CartItem.vue
│   │   ├── CartSummary.vue
│   │   └── CartDrawer.vue
│   ├── product/
│   │   ├── ProductCard.vue
│   │   ├── ProductGallery.vue
│   │   └── ProductReviews.vue
│   └── shared/
│       ├── Button.vue
│       └── Modal.vue
├── pages/
│   ├── products/
│   │   └── [id].vue
│   ├── cart.vue
│   └── index.vue
├── stores/
│   ├── cart.js
│   ├── product.js
│   └── user.js
└── composables/
    ├── useCart.js
    └── useProduct.js

Parece organizado, certo? Mas vamos pensar em um cenário real:

"Preciso implementar uma nova feature no carrinho"

Você vai precisar:

Navegar até components/cart/ para os componentes
Pular para pages/cart.vue para a página
Ir em stores/cart.js para a lógica de estado
Verificar composables/useCart.js para funções auxiliares
Talvez até api/cart.js se tiver separado

São 5 diretórios diferentes para trabalhar em uma única feature. Multiplique isso por cada desenvolvedor do time, cada feature, cada dia... e você entende por que projetos grandes se tornam difíceis de manter.

Nuxt Layers: A Revolução Silenciosa

Com o Nuxt 3, veio uma feature que passou meio despercebida mas que é revolucionária: Nuxt Layers. Como Dave Stewart explica em seu artigo sobre arquitetura modular, Layers permitem reorganizar completamente a estrutura do projeto.

Em vez de organizar por tipo de arquivo, organizamos por domínio:

meu-ecommerce/
├── layers/
│   ├── cart/                    # Tudo sobre carrinho
│   │   ├── components/
│   │   │   ├── CartItem.vue
│   │   │   ├── CartSummary.vue
│   │   │   └── CartDrawer.vue
│   │   ├── pages/
│   │   │   └── cart.vue
│   │   ├── stores/
│   │   │   └── cart.js
│   │   ├── composables/
│   │   │   └── useCart.js
│   │   └── nuxt.config.ts       # Config específica do cart
│   │
│   ├── product/                 # Tudo sobre produtos
│   │   ├── components/
│   │   ├── pages/
│   │   ├── stores/
│   │   └── nuxt.config.ts
│   │
│   └── catalog/                 # Tudo sobre catálogo
│       ├── components/
│       ├── pages/
│       ├── stores/
│       └── nuxt.config.ts
└── nuxt.config.ts               # Config principal

Como Funciona na Prática

Cada layer é como uma "mini-aplicação" Vue. Tem sua própria estrutura, suas próprias configurações, seus próprios módulos. O Nuxt então "costura" tudo junto em tempo de build.

// nuxt.config.ts principal
export default defineNuxtConfig({
  extends: [
    './layers/cart',
    './layers/product',
    './layers/catalog'
  ]
})

E cada layer pode ter sua própria configuração:

// layers/cart/nuxt.config.ts
export default defineNuxtConfig({
  // Módulos específicos do carrinho
  modules: ['@vueuse/nuxt'],

  // Components do carrinho
  components: {
    dirs: [{
      path: './components',
      prefix: 'Cart'  // CartItem, CartSummary, etc.
    }]
  }
})

Os Benefícios Transformadores

1. Coesão Natural de Domínio

Quando você precisa trabalhar no carrinho, tudo está em layers/cart. Não precisa ficar pulando entre pastas. É como ter um mini-projeto dedicado só para aquela feature.

# Trabalhando no carrinho? É só isso:
cd layers/cart
# Todos os arquivos relacionados estão aqui

2. Desenvolvimento Verdadeiramente Paralelo

Com domínios isolados, times diferentes podem trabalhar sem pisar no pé um do outro:

Time A trabalhando em layers/checkout
Time B refatorando layers/product
Time C criando nova feature em layers/recommendations

Menos conflitos no Git, menos "quem mexeu no meu componente?", menos stress.

3. Onboarding Simplificado

Novo dev no time? Em vez de explicar a arquitetura inteira:

"Você vai cuidar do catálogo. Está tudo em layers/catalog. É como se fosse uma aplicação Vue separada, mas integrada com o resto."

Pronto. Em 5 minutos a pessoa já está produtiva.

4. Boundaries Naturais e Encapsulamento

Cada layer expõe apenas o que precisa ser público. O resto fica encapsulado:

// layers/cart/index.ts - Interface pública
export { useCart } from './composables/useCart'
export { CartButton } from './components/CartButton'
// CartDrawer, CartLogic, etc. ficam privados

5. Preparação para o Futuro

Hoje você tem um monólito modular. Amanhã, se precisar, pode:

Extrair uma layer como pacote NPM
Transformar em micro-frontend
Mover para um repo separado
Criar uma aplicação independente

A arquitetura já está pronta para evolução.

Cenários Onde Brilha (e Onde Não)

Cenários Perfeitos ✅

1. E-commerce Médio/Grande

Domínios claros: Catálogo, Produto, Carrinho, Checkout, User
Features complexas mas independentes
Múltiplos times ou desenvolvedores

2. Aplicações SaaS B2B

Dashboard, Reports, Settings, Integrations
Cada módulo com suas próprias regras e complexidades
Necessidade de evolução independente

3. Portais e Marketplaces

Área do vendedor, área do comprador, admin
Diferentes experiências e necessidades
Times especializados por área

4. Aplicações Multi-tenant

Core compartilhado
Customizações por cliente em layers separadas
Facilita white-label

Onde Talvez Não Faça Sentido ❌

1. Landing Pages e Sites Institucionais

Poucos componentes
Sem domínios claros de negócio
Complexidade desnecessária

2. MVPs e Protótipos

Velocidade > Estrutura
Mudanças constantes de escopo
Time muito pequeno (1-2 devs)

3. Aplicações Hipersimples

CRUD básico
Menos de 20 componentes
Sem perspectiva de crescimento

Comparação com Outras Abordagens

Monorepo com Workspaces

monorepo/
├── packages/
│   ├── cart/
│   ├── product/
│   └── shared/
└── apps/
    └── main-app/

Prós do Monorepo:

Separação física total
Versionamento independente
Pode publicar no NPM

Prós do Nuxt Layers:

Menos complexidade de configuração
Build único e otimizado
Melhor DX (developer experience)
HMR funcionando perfeitamente

Micro-frontends

Micro-frontends são o extremo da modularização - aplicações completamente independentes que se juntam no browser.

Quando Micro-frontends fazem sentido:

Times completamente independentes
Tecnologias diferentes (Vue + React + Angular)
Deploy independente é crítico
Escala massiva (100+ devs)

Quando Nuxt Layers é melhor:

Time único ou poucos times
Stack Vue/Nuxt padronizada
Quer evitar complexidade de orquestração
Performance é prioridade

Implementando na Prática: Exemplo Simples

Vamos ver um exemplo minimalista de como estruturar um blog + loja:

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    './layers/base',    // Compartilhados
    './layers/blog',    // Blog com Nuxt Content
    './layers/shop'     // Loja simples
  ]
})

// layers/blog/nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/content'],

  content: {
    sources: {
      blog: {
        prefix: '/blog',
        base: './layers/blog/content'
      }
    }
  }
})

<!-- layers/shop/pages/shop.vue -->
<template>
  <div>
    <h1>Nossa Loja</h1>
    <ProductGrid :products="products" />
    <!-- ProductGrid está em layers/shop/components/ -->
  </div>
</template>

<script setup>
// Tudo local ao domínio shop
import { useShopStore } from '../stores/shop'
const shop = useShopStore()
const products = await shop.loadProducts()
</script>

Migração Gradual: O Segredo do Sucesso

A beleza desta arquitetura é que você não precisa reescrever tudo. Pode migrar gradualmente:

Fase 1: Identificar Domínios

Liste os domínios óbvios da sua aplicação. Geralmente são as "grandes áreas" que os usuários veem.

Fase 2: Criar Layer Base

Mova componentes compartilhados, utils, composables genéricos.

Fase 3: Migrar um Domínio Piloto

Escolha o domínio mais isolado (geralmente algo como "About" ou "Blog") e migre como teste.

Fase 4: Expandir Gradualmente

Um domínio por vez, conforme o time tem tempo. Não é um big bang, é evolução.

O Futuro é Modular

A arquitetura modular não é apenas uma moda ou uma forma diferente de organizar pastas. É uma mudança fundamental em como pensamos sobre a estrutura de aplicações frontend.

Como Eric Evans explica em Domain-Driven Design, software deve refletir o domínio do negócio. Com Nuxt Layers, finalmente temos uma forma elegante de fazer isso no frontend.

Conclusão: Pronto para o Próximo Passo?

Se você chegou até aqui, provavelmente está pensando: "Ok, a teoria é linda, mas como eu implemento isso de verdade?"

Ótima pergunta! No próximo artigo, vamos sair da teoria e construir um e-commerce completo do zero usando Nuxt Layers. Vamos implementar:

Sistema de catálogo com filtros e busca
Páginas de produto com galeria e reviews
Carrinho de compras com persistência
Integração real entre as layers
Testes, deploy e otimizações

Com código real, funcionando, que você pode copiar e adaptar.

Recursos para se Aprofundar

Documentação Oficial Nuxt Layers - A fonte definitiva
Nuxt Layers Unwrapped - Artigo detalhado de Dave Stewart
Domain-Driven Design - Eric Evans sobre modelagem por domínio
Building Evolutionary Architectures - Sobre arquiteturas que evoluem

Configuração e instalação do Nuxt 3

Gabriel Caiana — Thu, 02 Feb 2023 20:08:00 +0000

O Nuxt 3 é uma ferramenta poderosa para desenvolvimento de aplicações Vue.js. É uma abordagem baseada em framework que oferece uma série de recursos para ajudar você a criar aplicações avançadas com facilidade. Neste artigo, vamos cobrir os passos para configurar e instalar o Nuxt 3.

Instalação do Nuxt 3

A maneira mais fácil de instalar o Nuxt 3 é usando o CLI (Command Line Interface) Nuxt. Para fazer isso, você precisa ter o Node.js e o NPM (Node Package Manager) instalados em sua máquina. Depois de instalá-los, você pode executar o seguinte comando no seu terminal:

npx create-nuxt-app nome_da_sua_aplicacao

Configuração do Nuxt 3

Após a instalação, você precisará configurar o Nuxt 3 para atender às suas necessidades. A configuração principal é feita no arquivo nuxt.config.js, localizado na raiz da sua aplicação. Nesse arquivo, você pode especificar configurações como o título da sua aplicação, descrição, etc.

Inicialização do Nuxt 3

Depois de configurar o Nuxt 3, você pode iniciá-lo executando o seguinte comando no terminal:

npm run dev

Isso fará com que o Nuxt 3 inicie em modo de desenvolvimento, permitindo que você visualize sua aplicação em seu navegador.

Conclusão

Como você pode ver, a configuração e instalação do Nuxt 3 são simples e diretas. Além disso, o Nuxt 3 fornece uma série de recursos e opções para ajudá-lo a criar aplicações avançadas com facilidade.

Como adicionar a análise de pacotes do webpack em seu projeto nuxt

Gabriel Caiana — Thu, 02 Feb 2023 19:35:29 +0000

Visualize o tamanho dos arquivos de saída do webpack com um mapa de árvore interativo dentro do seu projeto com nuxtjs.

Sabemos como é importante colocar em produção aplicações que tenham o melhor desempenho possível, porém conforme começamos a desenvolver um projeto adicionamos diversos pacotes para determinadas tarefas e no final isso terá um impacto no desempenho da aplicação, como podemos análisar isso utilizando o nuxtjs?

Recentemente descobri uma forma muito fácil e interativa para mapear e análisar os pacotes que estão sendo utilizados no projeto, podemos criar um comando simples no package.json da seguinte forma:

"scripts": { "dev": "nuxt", "build": "nuxt build", "analyze": "nuxt build --analyze" }

ou podemos executar direto no terminal com yarn

yarn build --analyze

ou até mesmo utilizando o comando npx

npx nuxt build --analyze

com isso o webpack analyzer deve ser inicializado em seu navegador e com isso podemos visualizar toda a árvore de pacotes que o projeto está utilizando

Temos também uma barra a esquerda que permite que você escolha quais pedaços mostrar com os seus devidos tamanhos. podemos ver um exemplo disso na imagem abaixo:

Você também pode clicar duas vezes nas caixas, passar o mouse sobre elas para obter mais detalhes e clicar com o botão direito em um pedaço para ocultá-lo facilmente ou para ocultar todos os outros pedaços.

Espero que esse artigo possa ajudar você a analisar seu projeto e melhora-lo, vejo você no próximo post.

Link: [https://www.npmjs.com/package/webpack-bundle-analyzer]