Como modularizar frontend de verdade

O problema

Quando frontend cresce, surge a vontade de “modularizar tudo”.

Isso pode melhorar bastante.

Mas também pode produzir uma reforma cosmética:

• mais pastas
• mais index.ts
• mais reexport
• mais nomes sofisticados

e quase nenhuma melhora real no jeito como a base evolui.

Se a mudança não reduz:

• raio de impacto
• import cruzado
• custo de leitura
• medo de mexer

então provavelmente ainda não foi modularização de verdade.

Modelo mental

Módulo bom cria fronteira de mudança.

Ou seja:

• quem mexe dentro dele não precisa entender tudo fora
• quem usa de fora não precisa conhecer detalhe interno
• a dependência entra por pontos mais previsíveis

Em frase curta:

modularizar não é quebrar o frontend em mais pedaços. É fazer cada pedaço depender de menos contexto para continuar saudável.

O que modularização boa costuma entregar

1. Leitura mais local

A pessoa abre um fluxo e consegue entender:

• onde começa
• quem compõe a tela
• onde está a lógica principal
• o que é detalhe interno

Sem turismo arquitetural por vinte arquivos aleatórios.

2. Superfície pública menor

Módulo bom expõe pouco e esconde bastante.

Se tudo fica importável de qualquer lugar, a fronteira é fraca.

3. Menor raio de mudança

Quando você altera algo em um módulo, o objetivo é não disparar efeito colateral em áreas demais.

Se qualquer ajuste exige tocar metade da aplicação, a estrutura ainda não está ajudando.

Sinais de teatro arquitetural

Alguns cheiros aparecem rápido:

• pasta profunda com pouco critério
• barrel em todo nível
• nomes genéricos como core, common, base, utils
• feature importando detalhes internos de outra feature
• estrutura sofisticada com a mesma bagunça de dependências

Isso cria sensação de arquitetura, mas não dá segurança real.

Exemplo simples

Imagine um frontend de painel administrativo.

Versão teatral:

• modules/
• shared/
• core/
• common/
• presentation/
• domain/
• infra/

Tudo existe.

Mas:

• componentes de faturamento importam utilitário de onboarding
• hook de busca depende de store global sem fronteira
• detalhe de API vaza para tela

Versão mais honesta:

• cada área importante tem sua pasta
• existe ponto de entrada claro
• detalhes ficam mais locais
• shared é pequeno e criterioso
• import cruzado é exceção, não norma

Talvez pareça menos “arquitetado” no print da árvore.

Mas costuma ser mais sustentável.

Uma forma prática de começar

Se a base já está grande, modularizar melhor raramente começa com migração heroica.

Costuma funcionar melhor assim:

1. escolha um fluxo importante e dolorido
2. identifique o que realmente é entrada pública daquele pedaço
3. reduza import direto em detalhes internos
4. agrupe o que muda junto
5. deixe o resto para depois

Isso cria módulo de verdade aos poucos.

O papel da disciplina de dependência

Muita modularização falha porque a árvore muda e as regras de dependência continuam soltas.

Se qualquer arquivo pode importar qualquer outro:

• shared cresce errado
• módulo perde fronteira
• refactor fica arriscado

Mesmo sem ferramenta formal, já ajuda muito explicitar acordos como:

• feature não importa detalhe interno de outra feature
• design system não conhece domínio
• shared não vira despejo de tudo que sobrou

Como um senior pensa

Quem já apanhou de frontend grande normalmente avalia modularização por efeito real:

• ficou mais fácil mexer?
• o review ficou mais local?
• os imports ficaram mais previsíveis?
• o time entende melhor onde cada coisa mora?

Essa régua é melhor do que qualquer discussão puramente estética sobre árvore de diretórios.

Ângulo de entrevista

Esse tema aparece em:

• system design frontend
• perguntas sobre escalar base React
• discussões de legado e refatoração

Resposta fraca:

eu organizaria por módulos

Resposta forte:

• explica qual fronteira quer proteger
• mostra como reduzir acoplamento
• fala de superfície pública, dependência e raio de mudança

Isso mostra que você não está confundindo pasta com arquitetura.

Fechando a ideia

Modularizar frontend vale quando o sistema fica mais previsível para quem constrói e para quem mantém.

Se a estrutura nova só produz mais camadas, mais nomes e mais reexport, ela pode estar servindo mais ao ego da arquitetura do que ao produto.

Boa modularização não faz a árvore parecer sofisticada. Faz a mudança parecer menos perigosa.