---
title: "PNPM Catalogs: Catálogo Central de Versões Recomendadas para Microfrontends"
slug: pnpm-catalogs
date: 2025-05-13
category: "Microfrontends"
tags: ["pnpm", "catalogs", "dependencies", "microfrontends", "monorepo", "governance", "package-management"]
readTime: "4 min"
excerpt: "Como usar PNPM Catalogs para padronizar dependências entre projetos, melhorar governança e organizar versões por categoria em cenários de microfrontends e monorepos."
url: https://eliseu.dev/blog/pnpm-catalogs
---

Tenho usado o **pnpm catalogs** como estratégia para padronizar e categorizar dependências entre projetos — e tem funcionado muito bem, principalmente em contextos com múltiplos repositórios ou monorepos.

A ideia é simples: **Criar um catálogo com versões recomendadas das dependências** e consumi-las via `catalog:<nome>` nos projetos.

## 🏗️ Como Funciona

### Exemplo no `pnpm-workspace.yaml`:

```yaml
catalogs:
  core:
    react: ^18.2.0
    axios: ^1.6.0
  lint:
    eslint: ^8.57.0
    prettier: ^3.2.5
  test:
    vitest: ^1.5.0
    cypress: ^13.0.0
```

### E no `package.json` dos projetos:

```json
{
  "dependencies": {
    "react": "catalog:core",
    "axios": "catalog:core"
  },
  "devDependencies": {
    "eslint": "catalog:lint",
    "vitest": "catalog:test"
  }
}
```

## ✅ O que Isso Resolve na Prática

### **1. Padronização de Versões**
- ✅ **Versões consistentes** entre múltiplos times
- ✅ **Evita conflitos** de dependências
- ✅ **Facilita debugging** e troubleshooting

### **2. Organização por Categoria**
- ✅ **Dependências agrupadas** por tipo de uso (core, test, lint, etc.)
- ✅ **package.json mais semântico** e legível
- ✅ **Separação clara** entre runtime e dev dependencies

### **3. Governança Melhorada**
- ✅ **Upgrades centralizados** e controlados
- ✅ **Auditorias facilitadas** de segurança
- ✅ **Evita acoplamentos** desnecessários

### **4. Developer Experience**
- ✅ **Instalação simplificada** com `pnpm install`
- ✅ **Resolução automática** de versões
- ✅ **Integração com VSCode** via extensão

## 🛠️ Configuração Prática

### **1. Estrutura do Workspace**

```yaml
# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'
  - 'microfrontends/*'

catalogs:
  # Dependências principais do projeto
  core:
    react: ^18.2.0
    react-dom: ^18.2.0
    axios: ^1.6.0
    lodash: ^4.17.21
  
  # Ferramentas de desenvolvimento
  dev:
    typescript: ^5.3.0
    vite: ^5.0.0
    @types/node: ^20.10.0
  
  # Linting e formatação
  lint:
    eslint: ^8.57.0
    prettier: ^3.2.5
    @typescript-eslint/eslint-plugin: ^6.0.0
  
  # Testes
  test:
    vitest: ^1.5.0
    cypress: ^13.0.0
    @testing-library/react: ^14.0.0
  
  # Design System (para microfrontends)
  design-system:
    @stencil/core: ^4.0.0
    storybook: ^7.6.0
```

### **2. Uso nos Microfrontends**

```json
// apps/spotify-mfe-listening/package.json
{
  "name": "spotify-mfe-listening",
  "dependencies": {
    "react": "catalog:core",
    "react-dom": "catalog:core",
    "axios": "catalog:core"
  },
  "devDependencies": {
    "typescript": "catalog:dev",
    "vite": "catalog:dev",
    "eslint": "catalog:lint",
    "vitest": "catalog:test"
  }
}
```

```json
// apps/spotify-mfe-discovery/package.json
{
  "name": "spotify-mfe-discovery",
  "dependencies": {
    "vue": "catalog:core",
    "axios": "catalog:core"
  },
  "devDependencies": {
    "typescript": "catalog:dev",
    "eslint": "catalog:lint",
    "vitest": "catalog:test"
  }
}
```

## 🔧 Melhorando a Developer Experience

### **PNPM Catalog Lens (VSCode Extension)**

Para melhorar a DX, instale a extensão **PNPM Catalog Lens** no VSCode. Ela mostra, direto no `package.json`, a versão real resolvida de cada pacote que está vindo do catálogo.

**Benefícios:**
- ✅ **Visibilidade clara** das versões resolvidas
- ✅ **Debugging facilitado** de conflitos
- ✅ **IntelliSense melhorado** para catalogs

### **Comandos Úteis**

```bash
# Instalar dependências com catalogs
pnpm install

# Verificar versões resolvidas
pnpm list

# Atualizar catalogs
pnpm update --recursive

# Verificar dependências desatualizadas
pnpm outdated --recursive
```

## 🎯 Cenários de Uso Ideais

### **Microfrontends**
- ✅ **Consistência visual** com design system
- ✅ **Versões sincronizadas** entre MFEs
- ✅ **Upgrades coordenados** sem quebrar integração

### **Monorepos**
- ✅ **Dependências compartilhadas** entre packages
- ✅ **Versionamento centralizado**
- ✅ **Builds mais rápidos** com cache otimizado

### **Multi-repos**
- ✅ **Padrões consistentes** entre projetos
- ✅ **Onboarding facilitado** para novos desenvolvedores
- ✅ **Manutenção simplificada** de dependências

## 📋 Exemplo Completo

### **Estrutura de Projeto**

```
project/
├── pnpm-workspace.yaml
├── apps/
│   ├── spotify-mfe-shell/
│   ├── spotify-mfe-listening/
│   └── spotify-mfe-discovery/
├── packages/
│   ├── design-system/
│   └── shared-utils/
└── microfrontends/
    ├── spotify-mfe-library/
    └── spotify-mfe-search/
```

### **Configuração do Workspace**

```yaml
# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'
  - 'microfrontends/*'

catalogs:
  core:
    react: ^18.2.0
    vue: ^3.4.0
    axios: ^1.6.0
  
  design-system:
    @stencil/core: ^4.0.0
    storybook: ^7.6.0
  
  dev:
    typescript: ^5.3.0
    vite: ^5.0.0
    eslint: ^8.57.0
    prettier: ^3.2.5
```

## 🚀 Benefícios em Produção

### **Para Times**
- ✅ **Menos conflitos** de dependências
- ✅ **Onboarding mais rápido** de novos desenvolvedores
- ✅ **Manutenção simplificada** de projetos

### **Para Arquitetura**
- ✅ **Upgrades coordenados** e seguros
- ✅ **Auditorias centralizadas** de segurança
- ✅ **Governança melhorada** de dependências

### **Para Produto**
- ✅ **Consistência** entre microfrontends
- ✅ **Performance otimizada** com cache compartilhado
- ✅ **Deploy mais confiável** com versões testadas

## 📚 Documentação Oficial

**PNPM Catalogs**: [https://pnpm.io/catalogs](https://pnpm.io/catalogs)

*Este artigo apresenta uma estratégia prática para gestão de dependências em projetos complexos. Para discussões técnicas, implementações ou dúvidas sobre PNPM Catalogs, me encontre no [LinkedIn](https://linkedin.com/in/eliseusantos) ou [GitHub](https://github.com/EliseuSantos).*