Voltar ao Blog
    Microfrontends

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

    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.

    13 de maio de 20254 min
    .md

    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.