0Pricing
Frontend Academy · Aula

Estrutura de pastas baseada em funcionalidades

Organizar o código por domínio funcional em vez de por tipo, manter testes, estilos e componentes junto do código correspondente e impor limites com eslint-plugin-boundaries.

Estrutura de pastas baseada em funcionalidades é uma aula grátis de Frontend Academy no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Frontend Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Frontend Academy inclui 4 aulas no total.

Duas formas de organizar o código

Você pode agrupar o código por tipo (components/, hooks/, services/, types/) ou por funcionalidade (auth/, checkout/, dashboard/ — cada uma contendo seus próprios componentes, hooks etc.). A organização por funcionalidade é melhor para aplicações médias e grandes.

Por tipo — a armadilha padrão

A estrutura clássica dos tutoriais de React agrupa tudo por tipo. Ela escala mal: cada alteração em um arquivo afeta várias pastas não relacionadas, e “encontrar todo o código de checkout” significa procurar com grep na árvore inteira.

// Type-based (avoid for large apps):
src/
  components/
    Button.tsx
    LoginForm.tsx
    CartItem.tsx
  hooks/
    useAuth.ts
    useCart.ts
  services/
    auth.ts
    cart.ts
  types/
    User.ts
    CartItem.ts

Estrutura por funcionalidade

Agrupe tudo o que está relacionado a uma funcionalidade em uma única pasta. É fácil de encontrar, fácil de excluir e fácil de compreender.

src/
  features/
    auth/
      LoginForm.tsx
      SignupForm.tsx
      useAuth.ts
      auth.service.ts
      auth.types.ts
      auth.test.tsx
    cart/
      CartItem.tsx
      CartSummary.tsx
      useCart.ts
      cart.service.ts
      cart.types.ts
  shared/
    components/
      Button.tsx
    hooks/
      useDebounce.ts

Co-localização dentro de uma funcionalidade

Uma pasta de funcionalidade contém: componentes, hooks, serviços, tipos e testes — todo o código necessário para esse domínio. Uma pessoa desenvolvedora nova quer entender auth? Abra auth/. Quer excluir auth? Exclua a pasta.

Compartilhado versus funcionalidade

O código usado por 2 ou mais funcionalidades vai para shared/ (ou lib/). O código usado por uma única funcionalidade permanece dentro dela. Resista à ideia de que “talvez seja reutilizável mais tarde” — espere o segundo uso antes de extraí-lo.

Regras de limite entre funcionalidades

As funcionalidades não devem importar umas das outras diretamente. Se duas funcionalidades precisarem compartilhar código, a parte compartilhada vai para shared/. Se precisarem coordenar ações, use eventos ou um armazenamento compartilhado no nível da aplicação.

Aplicando limites com ESLint

Use eslint-plugin-boundaries ou eslint-plugin-import para impor a regra: as funcionalidades podem importar de shared, mas não umas das outras.

// .eslintrc.json
{
  "plugins": ["boundaries"],
  "settings": {
    "boundaries/elements": [
      { "type": "feature", "pattern": "src/features/*" },
      { "type": "shared",  "pattern": "src/shared/*" }
    ]
  },
  "rules": {
    "boundaries/element-types": ["error", {
      "default": "disallow",
      "rules": [
        { "from": "feature", "allow": ["shared"] },
        { "from": "shared",  "allow": ["shared"] }
      ]
    }]
  }
}

API pública por funcionalidade

Cada funcionalidade exporta uma API pública por meio de features/auth/index.ts. O restante do código importa de '@/features/auth', e não de caminhos internos. Isso permite refatorar a implementação interna sem quebrar quem a utiliza.

// features/auth/index.ts
export { LoginForm } from './LoginForm';
export { useAuth } from './useAuth';
export type { User, AuthState } from './auth.types';

// Consumers:
import { LoginForm, useAuth } from '@/features/auth';
// NOT: import { LoginForm } from '@/features/auth/LoginForm';

Aninhando subfuncionalidades

Funcionalidades grandes podem ter subpastas: dashboard/widgets/, dashboard/charts/. Evite aninhar mais de 2 ou 3 níveis — pesquisar se torna trabalhoso.

Onde ficam as rotas

As páginas e rotas podem ficar em uma pasta de nível superior pages/ ou routes/. Elas são simples — extraem componentes e hooks das funcionalidades e os compõem.

src/
  pages/
    Dashboard.page.tsx   // composes Dashboard widgets from features/dashboard/
    Cart.page.tsx        // composes from features/cart/
  features/
  shared/

Migrando uma aplicação existente

Comece apenas pelas novas funcionalidades — coloque o código novo em features/. Não refatore tudo de uma vez. Conforme trabalhar nos arquivos antigos, mova-os gradualmente. As regras de limite do ESLint evitam regressões na nova estrutura.

Quando a organização por tipo ainda funciona

Para aplicações muito pequenas (com menos de 30 componentes) ou bibliotecas, a organização por tipo funciona bem. Use a organização por funcionalidade assim que tiver domínios de negócio distintos (autenticação, checkout, faturamento e configurações).

Verificação rápida

Qual é o principal benefício organizacional de agrupar o código por funcionalidade em vez de por tipo de arquivo?

Recapitulação: estrutura por funcionalidade

features/ contém código específico de cada domínio; shared/ contém utilitários usados entre funcionalidades. Cada funcionalidade exporta um index.ts público. As funcionalidades não importam umas das outras — apenas de shared. Aplique essa regra com eslint-plugin-boundaries. Páginas e rotas compõem funcionalidades. Faça a migração gradualmente. A organização por tipo funciona bem para aplicações pequenas.

Perguntas Frequentes

A aula “Estrutura de pastas baseada em funcionalidades” é grátis?

Sim — o texto completo de “Estrutura de pastas baseada em funcionalidades” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Frontend Academy, atualize para CoddyKit PRO. O curso de Frontend Academy inclui 4 aulas no total.

O que vou aprender em “Estrutura de pastas baseada em funcionalidades”?

Organizar o código por domínio funcional em vez de por tipo, manter testes, estilos e componentes junto do código correspondente e impor limites com eslint-plugin-boundaries. Você pratica Frontend Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Frontend Academy?

Nenhuma experiência prévia é necessária. Frontend Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.

Quanto tempo leva a aula “Estrutura de pastas baseada em funcionalidades”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Frontend Academy?

Sim. Cada aula de Frontend Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Design atómico: átomos, moléculas e organismos
  2. Configuração de monorepo com Turborepo
  3. Microfrontends: Module Federation
  4. Estrutura de pastas baseada em funcionalidades
← Voltar para Frontend Academy