PNPM Catalogs: Catálogo Central de Versões Recomendadas para Microfrontends

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:

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:

{
  "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

# 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

// 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"
  }
}

// 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

# 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

# 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

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 ou GitHub.