Grupos de Rotas e Organização de `app/`

Q: Os parênteses aparecem nas URLs?

Não. (auth)/login.tsx mapeia para /login, não /auth/login. Grupos existem puramente para organização de sistema de arquivos e limites de layout.

Q: Posso aninhar múltiplos grupos de rotas?

Sim - app/(app)/(tabs)/(hidden)/ é válido. Cada nome de grupo é removido. Evite aninhamento desnecessário que obscurece o mapa de rotas.

Q: O que é uma pasta privada?

Arquivos e pastas que começam com _ (exceto _layout.tsx) não são transformados em rotas. Use _components/, _hooks/, etc., para código não-rota colocalizado.

Q: Como os grupos interagem com deep links?

Deep links visam caminhos de URL, não nomes de grupos. /settings abre (app)/(tabs)/settings.tsx independentemente das pastas de grupo. Configure scheme em app.config.ts uma vez no nível do aplicativo.

Q: Devo compartilhar um layout raiz entre autenticação e aplicativo?

Sim - um app/_layout.tsx monta provedores para ambos os grupos. Separe navegadores por grupo ((auth)/_layout, (app)/_layout), não árvores de provedores duplicadas.

Q: Como organizar modais?

Crie (modals)/ com seu próprio _layout.tsx definindo presentation: "modal". Registre (modals) na pilha raiz. URLs permanecem /compose, não /modals/compose.

Q: Dois grupos podem ter uma rota de índice cada?

Ambos resolveriam para / - um conflito. Use um único app/index.tsx como o redirecionamento de entrada em vez disso.

Q: Como isso se mapeia para Feature-Sliced Design?

app/ é a camada de aplicativo do FSD (apenas roteamento). features/, entities/, shared/ vivem fora de app/. Grupos de rotas segmentam fluxos; fatias de funcionalidades segmentam domínios de negócios - veja ../architecture-design/feature-sliced-design-for-rn/feature-sliced-design-for-rn.md.

Q: Quando os URLs devem incluir o segmento explicitamente?

Quando marketing, SEO (web) ou documentação de suporte publicam o caminho - por exemplo, /pricing para uma página web pública. Use pastas normais, não grupos, quando o segmento deve aparecer na URL.

Q: Como documentar o mapa de rotas para novos contratados?

Mantenha uma tabela docs/routes.md: URL → caminho do arquivo → proprietário da funcionalidade. Atualize a cada novo grupo. Combine com rotas tipadas para que o TypeScript capture desvios.

Convenções de pastas (auth), (tabs) e privadas. Grupos de rotas mantêm árvores app/ grandes navegáveis sem poluir URLs ou caminhos de deep-link.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

app/
├── _layout.tsx                 # Provedores raiz + navegador superior
├── index.tsx                   # Hub de redirecionamento de entrada
├── (auth)/
│   ├── _layout.tsx             # Pilha de autenticação (sem cabeçalho)
│   ├── login.tsx               # /login
│   └── register.tsx            # /register
├── (app)/
│   ├── _layout.tsx             # Shell de guarda autenticado
│   └── (tabs)/
│       ├── _layout.tsx
│       ├── index.tsx           # /
│       └── settings.tsx        # /settings
├── (modals)/
│   ├── _layout.tsx             # presentation: modal
│   └── compose.tsx             # /compose
└── _components/                # Privado - NÃO é uma rota
    └── ScreenChrome.tsx

// app/(app)/_layout.tsx - shell de autenticação mínimo
import { Redirect, Stack } from "expo-router";
import { useSession } from "@/features/auth";
 
export default function AppShellLayout() {
  const { session, isLoading } = useSession();
 
  if (isLoading) return null;
  if (!session) return <Redirect href="/login" />;
 
  return <Stack screenOptions={{ headerShown: false }} />;
}

Quando usar isso:

Separar fluxos de autenticação vs autenticados com layouts diferentes
Agrupar modais para opções compartilhadas de presentation: "modal"
Organizar abas sem /tabs em cada URL
Colocar ajudantes não-rota em _components/ ao lado dos layouts

Exemplo de Trabalho

Uma árvore com formato de produção com grupo de autenticação, shell de aplicativo, abas, modais e pastas privadas.

// app/_layout.tsx
import { Stack } from "expo-router";
import { AppProviders } from "@/app-providers";
 
export default function RootLayout() {
  return (
    <AppProviders>
      <Stack screenOptions={{ headerShown: false }}>
        <Stack.Screen name="index" />
        <Stack.Screen name="(auth)" />
        <Stack.Screen name="(app)" />
        <Stack.Screen name="(modals)" options={{ presentation: "modal" }} />
      </Stack>
    </AppProviders>
  );
}

// app/(auth)/_layout.tsx
import { Stack } from "expo-router";
 
export default function AuthLayout() {
  return (
    <Stack screenOptions={{ headerShown: false, animation: "fade" }}>
      <Stack.Screen name="login" />
      <Stack.Screen name="register" />
    </Stack>
  );
}

// app/(modals)/_layout.tsx
import { Stack } from "expo-router";
 
export default function ModalsLayout() {
  return (
    <Stack
      screenOptions={{
        presentation: "modal",
        headerShown: true,
      }}
    />
  );
}

// app/(app)/(tabs)/_layout.tsx
import { Tabs } from "expo-router";
 
export default function TabsLayout() {
  return (
    <Tabs>
      <Tabs.Screen name="index" options={{ title: "Home" }} />
      <Tabs.Screen name="settings" options={{ title: "Settings" }} />
    </Tabs>
  );
}

// app/_components/LoadingGate.tsx - importar de layouts; nunca roteado
import { ActivityIndicator, View } from "react-native";
 
export function LoadingGate() {
  return (
    <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
      <ActivityIndicator />
    </View>
  );
}

Mapa de URL (grupos omitidos do caminho):
 
/login           → (auth)/login.tsx
/register        → (auth)/register.tsx
/                → (app)/(tabs)/index.tsx
/settings        → (app)/(tabs)/settings.tsx
/compose         → (modals)/compose.tsx

Mergulho Profundo

Sintaxe de grupo de rotas

Padrão	Impacto na URL	Propósito
`(auth)/login.tsx`	`/login`	Nome do grupo omitido da URL
`(tabs)/index.tsx`	`/`	Organizar arquivos de abas
`[id].tsx`	`/:id`	Segmento dinâmico (não é um grupo)
`_layout.tsx`	-	Navegador para a pasta
`_components/`	-	Pasta privada (prefixo underscore)

Grupos podem aninhados: (app)/(tabs)/ é válido - ambos os nomes são removidos da URL
Grupos irmãos no mesmo nível se fundem em uma única árvore de rotas - evite nomes de rotas duplicados entre grupos
Grupos de rotas não são grupos de layout - você ainda precisa de _layout.tsx por pasta para navegadores

Princípios de organização

app/                          features/
├── apenas roteamento e layouts ├── lógica de negócios
├── re-exportações            ├── hooks e API
├── redirecionamentos         └── telas de UI
└── _components/ (privado)

Uma preocupação por grupo - (auth) para login, (app) para shell logado, (modals) para overlays
Espelhe nomes de funcionalidades - app/(app)/(tabs)/orders/ mapeia para features/orders/
Mantenha index.tsx raiz leve - apenas hub de redirecionamento; veja Redirecionamentos e Rotas de Índice
Limite a profundidade da pasta em 4 - app/(app)/(tabs)/orders/[id].tsx é suficiente; caminhos mais profundos sinalizam hora de refatorar

Pastas privadas e colocação

app/(tabs)/
├── _layout.tsx
├── _components/
│   └── TabIcon.tsx
├── index.tsx
└── profile.tsx

_prefixo marca arquivos/pastas não roteáveis - Expo Router os ignora para geração de URL
Coloque componentes apenas de layout em _components/ - não os coloque em features/ a menos que sejam reutilizados
+html.tsx, +not-found.tsx são arquivos especiais - aprenda seus papéis antes de personalizar web/not-found

Padrão de múltiplos grupos raiz

// app/_layout.tsx - registro explícito impede descoberta automática ambígua
<Stack>
  <Stack.Screen name="(auth)" />
  <Stack.Screen name="(app)" />
</Stack>

<Stack.Screen name="(auth)" /> explícito documenta segmentos de nível superior para revisores e mantém as opções de tela centralizadas.

Armadilhas

Rotas duplicadas entre grupos - (auth)/index.tsx e (app)/index.tsx ambos mapeiam para /. Correção: Um único hub de redirecionamento app/index.tsx; um grupo é o proprietário de /.
Esquecer parênteses do grupo - auth/login.tsx cria /auth/login, quebrando links de marketing. Correção: Renomeie para (auth)/login.tsx.
Lógica de negócios em _layout.tsx - busca de dados em layouts é executada em cada navegação filho. Correção: Apenas redirecionamento de autenticação; telas são proprietárias dos dados.
Grupo (app) gigante - todas as telas despejadas sob um único grupo. Correção: Subgrupos (tabs), (modals), pastas de funcionalidades.
_components sem underscore - components/Header.tsx se torna a rota /components/Header. Correção: Prefixe pastas privadas com _.
router.push entre grupos com caminho incorreto - chamar /(app)/settings inclui o grupo em algumas APIs. Correção: Use caminhos de URL /settings ou objetos Href tipados.
app/ compartilhado em monorepo - aplicativos white-label divergem nas árvores de rotas. Correção: Separe apps/brand-a/app/ por binário - veja ../project-setup/multiple-apps-in-one-repo/multiple-apps-in-one-repo.md.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Grupos de rotas `(name)`	Organizar sem segmentos de URL	Você precisa de `/auth/login` na URL pública
Árvore `app/` plana	<10 rotas no total	Esquadrões paralelos editando uma pasta diariamente
`src/routes` manual React Navigation	Brownfield sem roteamento baseado em arquivo	Novos aplicativos greenfield SDK 57
Flags de funcionalidades para seções	Abas sazonais	Divisão permanente de autenticação vs aplicativo
Aplicativos Expo separados	Produtos verdadeiramente diferentes	Variantes white-label - use configuração em vez disso
Espelhamento profundo de pastas do organograma	Nunca recomendado	-

FAQs

Os parênteses aparecem nas URLs?

Não. (auth)/login.tsx mapeia para /login, não /auth/login. Grupos existem puramente para organização de sistema de arquivos e limites de layout.

Posso aninhar múltiplos grupos de rotas?

Sim - app/(app)/(tabs)/(hidden)/ é válido. Cada nome de grupo é removido. Evite aninhamento desnecessário que obscurece o mapa de rotas.

O que é uma pasta privada?

Arquivos e pastas que começam com _ (exceto _layout.tsx) não são transformados em rotas. Use _components/, _hooks/, etc., para código não-rota colocalizado.

Como os grupos interagem com deep links?

Deep links visam caminhos de URL, não nomes de grupos. /settings abre (app)/(tabs)/settings.tsx independentemente das pastas de grupo. Configure scheme em app.config.ts uma vez no nível do aplicativo.

Devo compartilhar um layout raiz entre autenticação e aplicativo?

Sim - um app/_layout.tsx monta provedores para ambos os grupos. Separe navegadores por grupo ((auth)/_layout, (app)/_layout), não árvores de provedores duplicadas.

Como organizar modais?

Crie (modals)/ com seu próprio _layout.tsx definindo presentation: "modal". Registre (modals) na pilha raiz. URLs permanecem /compose, não /modals/compose.

Dois grupos podem ter uma rota de índice cada?

Ambos resolveriam para / - um conflito. Use um único app/index.tsx como o redirecionamento de entrada em vez disso.

Como isso se mapeia para Feature-Sliced Design?

app/ é a camada de aplicativo do FSD (apenas roteamento). features/, entities/, shared/ vivem fora de app/. Grupos de rotas segmentam fluxos; fatias de funcionalidades segmentam domínios de negócios - veja ../architecture-design/feature-sliced-design-for-rn/feature-sliced-design-for-rn.md.

Quando os URLs devem incluir o segmento explicitamente?

Quando marketing, SEO (web) ou documentação de suporte publicam o caminho - por exemplo, /pricing para uma página web pública. Use pastas normais, não grupos, quando o segmento deve aparecer na URL.

Como documentar o mapa de rotas para novos contratados?

Mantenha uma tabela docs/routes.md: URL → caminho do arquivo → proprietário da funcionalidade. Atualize a cada novo grupo. Combine com rotas tipadas para que o TypeScript capture desvios.

Relacionados

Fundamentos do Expo Router - fundamentos de roteamento baseado em arquivo
Redirecionamentos e Rotas de Índice - hub de redirecionamento app/index.tsx
Abas e Gavetas - padrões de layout (tabs) e (drawer)
Navegação em Pilha - opções de pilha por grupo
../architecture-design/feature-sliced-design-for-rn/feature-sliced-design-for-rn.md - limites de funcionalidade vs app/
../expo-rules/navigation-and-routing-rules/navigation-and-routing-rules.md - checklist de revisão de estrutura

Versões da Pilha: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

app/
├── _layout.tsx                 # Provedores raiz + navegador superior
├── index.tsx                   # Hub de redirecionamento de entrada
├── (auth)/
│   ├── _layout.tsx             # Pilha de autenticação (sem cabeçalho)
│   ├── login.tsx               # /login
│   └── register.tsx            # /register
├── (app)/
│   ├── _layout.tsx             # Shell de guarda autenticado
│   └── (tabs)/
│       ├── _layout.tsx
│       ├── index.tsx           # /
│       └── settings.tsx        # /settings
├── (modals)/
│   ├── _layout.tsx             # presentation: modal
│   └── compose.tsx             # /compose
└── _components/                # Privado - NÃO é uma rota
    └── ScreenChrome.tsx

// app/(app)/_layout.tsx - shell de autenticação mínimo
import { Redirect, Stack } from "expo-router";
import { useSession } from "@/features/auth";
 
export default function AppShellLayout() {
  const { session, isLoading } = useSession();
 
  if (isLoading) return null;
  if (!session) return <Redirect href="/login" />;
 
  return <Stack screenOptions={{ headerShown: false }} />;
}

Quando usar isso:

Separar fluxos de autenticação vs autenticados com layouts diferentes
Agrupar modais para opções compartilhadas de presentation: "modal"
Organizar abas sem /tabs em cada URL
Colocar ajudantes não-rota em _components/ ao lado dos layouts

Exemplo de Trabalho

Uma árvore com formato de produção com grupo de autenticação, shell de aplicativo, abas, modais e pastas privadas.

// app/_layout.tsx
import { Stack } from "expo-router";
import { AppProviders } from "@/app-providers";
 
export default function RootLayout() {
  return (
    <AppProviders>
      <Stack screenOptions={{ headerShown: false }}>
        <Stack.Screen name="index" />
        <Stack.Screen name="(auth)" />
        <Stack.Screen name="(app)" />
        <Stack.Screen name="(modals)" options={{ presentation: "modal" }} />
      </Stack>
    </AppProviders>
  );
}

// app/(auth)/_layout.tsx
import { Stack } from "expo-router";
 
export default function AuthLayout() {
  return (
    <Stack screenOptions={{ headerShown: false, animation: "fade" }}>
      <Stack.Screen name="login" />
      <Stack.Screen name="register" />
    </Stack>
  );
}

// app/(modals)/_layout.tsx
import { Stack } from "expo-router";
 
export default function ModalsLayout() {
  return (
    <Stack
      screenOptions={{
        presentation: "modal",
        headerShown: true,
      }}
    />
  );
}

// app/(app)/(tabs)/_layout.tsx
import { Tabs } from "expo-router";
 
export default function TabsLayout() {
  return (
    <Tabs>
      <Tabs.Screen name="index" options={{ title: "Home" }} />
      <Tabs.Screen name="settings" options={{ title: "Settings" }} />
    </Tabs>
  );
}

// app/_components/LoadingGate.tsx - importar de layouts; nunca roteado
import { ActivityIndicator, View } from "react-native";
 
export function LoadingGate() {
  return (
    <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
      <ActivityIndicator />
    </View>
  );
}

Mapa de URL (grupos omitidos do caminho):
 
/login           → (auth)/login.tsx
/register        → (auth)/register.tsx
/                → (app)/(tabs)/index.tsx
/settings        → (app)/(tabs)/settings.tsx
/compose         → (modals)/compose.tsx

Mergulho Profundo

Sintaxe de grupo de rotas

Padrão	Impacto na URL	Propósito
`(auth)/login.tsx`	`/login`	Nome do grupo omitido da URL
`(tabs)/index.tsx`	`/`	Organizar arquivos de abas
`[id].tsx`	`/:id`	Segmento dinâmico (não é um grupo)
`_layout.tsx`	-	Navegador para a pasta
`_components/`	-	Pasta privada (prefixo underscore)

Grupos podem aninhados: (app)/(tabs)/ é válido - ambos os nomes são removidos da URL
Grupos irmãos no mesmo nível se fundem em uma única árvore de rotas - evite nomes de rotas duplicados entre grupos
Grupos de rotas não são grupos de layout - você ainda precisa de _layout.tsx por pasta para navegadores

Princípios de organização

app/                          features/
├── apenas roteamento e layouts ├── lógica de negócios
├── re-exportações            ├── hooks e API
├── redirecionamentos         └── telas de UI
└── _components/ (privado)

Uma preocupação por grupo - (auth) para login, (app) para shell logado, (modals) para overlays
Espelhe nomes de funcionalidades - app/(app)/(tabs)/orders/ mapeia para features/orders/
Mantenha index.tsx raiz leve - apenas hub de redirecionamento; veja Redirecionamentos e Rotas de Índice
Limite a profundidade da pasta em 4 - app/(app)/(tabs)/orders/[id].tsx é suficiente; caminhos mais profundos sinalizam hora de refatorar

Pastas privadas e colocação

app/(tabs)/
├── _layout.tsx
├── _components/
│   └── TabIcon.tsx
├── index.tsx
└── profile.tsx

_prefixo marca arquivos/pastas não roteáveis - Expo Router os ignora para geração de URL
Coloque componentes apenas de layout em _components/ - não os coloque em features/ a menos que sejam reutilizados
+html.tsx, +not-found.tsx são arquivos especiais - aprenda seus papéis antes de personalizar web/not-found

Padrão de múltiplos grupos raiz

// app/_layout.tsx - registro explícito impede descoberta automática ambígua
<Stack>
  <Stack.Screen name="(auth)" />
  <Stack.Screen name="(app)" />
</Stack>

<Stack.Screen name="(auth)" /> explícito documenta segmentos de nível superior para revisores e mantém as opções de tela centralizadas.

Armadilhas

Rotas duplicadas entre grupos - (auth)/index.tsx e (app)/index.tsx ambos mapeiam para /. Correção: Um único hub de redirecionamento app/index.tsx; um grupo é o proprietário de /.
Esquecer parênteses do grupo - auth/login.tsx cria /auth/login, quebrando links de marketing. Correção: Renomeie para (auth)/login.tsx.
Lógica de negócios em _layout.tsx - busca de dados em layouts é executada em cada navegação filho. Correção: Apenas redirecionamento de autenticação; telas são proprietárias dos dados.
Grupo (app) gigante - todas as telas despejadas sob um único grupo. Correção: Subgrupos (tabs), (modals), pastas de funcionalidades.
_components sem underscore - components/Header.tsx se torna a rota /components/Header. Correção: Prefixe pastas privadas com _.
router.push entre grupos com caminho incorreto - chamar /(app)/settings inclui o grupo em algumas APIs. Correção: Use caminhos de URL /settings ou objetos Href tipados.
app/ compartilhado em monorepo - aplicativos white-label divergem nas árvores de rotas. Correção: Separe apps/brand-a/app/ por binário - veja ../project-setup/multiple-apps-in-one-repo/multiple-apps-in-one-repo.md.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Grupos de rotas `(name)`	Organizar sem segmentos de URL	Você precisa de `/auth/login` na URL pública
Árvore `app/` plana	<10 rotas no total	Esquadrões paralelos editando uma pasta diariamente
`src/routes` manual React Navigation	Brownfield sem roteamento baseado em arquivo	Novos aplicativos greenfield SDK 57
Flags de funcionalidades para seções	Abas sazonais	Divisão permanente de autenticação vs aplicativo
Aplicativos Expo separados	Produtos verdadeiramente diferentes	Variantes white-label - use configuração em vez disso
Espelhamento profundo de pastas do organograma	Nunca recomendado	-

FAQs

Os parênteses aparecem nas URLs?

Não. (auth)/login.tsx mapeia para /login, não /auth/login. Grupos existem puramente para organização de sistema de arquivos e limites de layout.

Posso aninhar múltiplos grupos de rotas?

Sim - app/(app)/(tabs)/(hidden)/ é válido. Cada nome de grupo é removido. Evite aninhamento desnecessário que obscurece o mapa de rotas.

O que é uma pasta privada?

Arquivos e pastas que começam com _ (exceto _layout.tsx) não são transformados em rotas. Use _components/, _hooks/, etc., para código não-rota colocalizado.

Como os grupos interagem com deep links?

Devo compartilhar um layout raiz entre autenticação e aplicativo?

Sim - um app/_layout.tsx monta provedores para ambos os grupos. Separe navegadores por grupo ((auth)/_layout, (app)/_layout), não árvores de provedores duplicadas.

Como organizar modais?

Crie (modals)/ com seu próprio _layout.tsx definindo presentation: "modal". Registre (modals) na pilha raiz. URLs permanecem /compose, não /modals/compose.

Dois grupos podem ter uma rota de índice cada?

Ambos resolveriam para / - um conflito. Use um único app/index.tsx como o redirecionamento de entrada em vez disso.

Como isso se mapeia para Feature-Sliced Design?

Quando os URLs devem incluir o segmento explicitamente?

Como documentar o mapa de rotas para novos contratados?

Mantenha uma tabela docs/routes.md: URL → caminho do arquivo → proprietário da funcionalidade. Atualize a cada novo grupo. Combine com rotas tipadas para que o TypeScript capture desvios.

Relacionados

Fundamentos do Expo Router - fundamentos de roteamento baseado em arquivo
Redirecionamentos e Rotas de Índice - hub de redirecionamento app/index.tsx
Abas e Gavetas - padrões de layout (tabs) e (drawer)
Navegação em Pilha - opções de pilha por grupo
../architecture-design/feature-sliced-design-for-rn/feature-sliced-design-for-rn.md - limites de funcionalidade vs app/
../expo-rules/navigation-and-routing-rules/navigation-and-routing-rules.md - checklist de revisão de estrutura

Versões da Pilha: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

Grupos de Rotas e Organização de app/

Buscar na documentação

Grupos de Rotas e Organização de app/

Grupos de Rotas e Organização de `app/`

Grupos de Rotas e Organização de `app/`