Blog

Como estruturar a navegação no React Native com TypeScript

24 de setembro de 2022 8 min de leitura

Domine o React Navigation v6 com TypeScript. Aprenda navegação com tipagem segura, passagem de parâmetros e padrões avançados de navegação em aplicações React Native.

Como estruturar a navegação no React Native com TypeScript
React NativeTypeScriptNavegaçãoReact Navigation

Aproveite as tipagens: React Navigation

Construir a navegação virou uma funcionalidade fundamental de qualquer aplicativo mobile hoje em dia. No mundo React Native, temos o React Navigation no bolso.

Este artigo mostra como uma implementação típica de React Navigation pode ser feita com TypeScript, comparando ao mesmo tempo diferentes estratégias de uso do TypeScript.

E, mais importante, ele também mostra como aproveitar ao máximo os recursos do TypeScript para construir uma arquitetura de navegação mais escalável.

Atenção: os exemplos deste artigo foram feitos com a versão @react-navigation@6.x.

Atenção: os métodos e estratégias que serão apresentados neste artigo não são obrigatórios nem algo que você precise seguir à risca. São apenas as minhas preferências, e achei útil compartilhá-las com quem lê este artigo. O React Navigation já tem uma seção incrível e muito bem documentada sobre o uso de typescript. Dito isso, você já consegue montar uma ótima estrutura de react-navigation com typescript só seguindo esta documentação.

Criando o Stack Navigator

Vamos ver como criar um stack navigator usando o pacote React Navigation.

Veja o exemplo abaixo, tirado do React Navigation:

import { createStackNavigator } from "@react-navigation/stack";
import * as React from "react";
import { View } from "react-native";

const Stack = createStackNavigator();

const Home = () => <View />;
const Notifications = () => <View />;
const Profile = () => <View />;
const Settings = () => <View />;

function AppStack() {
  return (
    <Stack.Navigator>
      <Stack.Screen name="Home" component={Home} />
      <Stack.Screen name="Notifications" component={Notifications} />
      <Stack.Screen name="Profile" component={Profile} />
      <Stack.Screen name="Settings" component={Settings} />
    </Stack.Navigator>
  );
}

Como dá para ver, não há nada específico de TypeScript aqui. Vamos adicionar um pouco de TypeScript a esse trecho de código.

import { createStackNavigator } from "@react-navigation/stack";
import * as React from "react";
import { View } from "react-native";

type AppStackParamList = {
  Home: undefined;
  Notifications: undefined;
  Profile: undefined;
  Settings: undefined;
};

const Home = () => <View />;
const Notifications = () => <View />;
const Profile = () => <View />;
const Settings = () => <View />;

const Stack = createStackNavigator<AppStackParamList>();

function AppStack() {
  return (
    <Stack.Navigator>
      <Stack.Screen name="Home" component={Home} />
      <Stack.Screen name="Notifications" component={Notifications} />
      <Stack.Screen name="Profile" component={Profile} />
      <Stack.Screen name="Settings" component={Settings} />
    </Stack.Navigator>
  );
}

Acima, adicionamos o tipo ParamList ao createStackNavigator. Mas espera: como sabemos que o createStackNavigator recebe um tipo genérico? Há algumas formas de descobrir. Revisar a documentação primeiro sempre foi uma boa prática. Neste exemplo, você vai notar que já existe uma seção sobre isso na documentação.

Por outro lado, supondo que essa tipagem específica do createStackNavigator não esteja documentada no site, uma forma possível de descobrir se a função tem a tipagem seria simplesmente pular para a definição de tipo da função. Pode assustar no começo, já que vai ter muitos types, interfaces e generics voando por todo lado, mas quanto mais você criar o hábito de pular para a definição de tipo, menos assustador isso vai ser.

Atualização!

Se você quer lidar com uma complexidade extra no typescript e também quer ignorar um utilitário de TS brilhante do time do React (React.ComponentProps), pode continuar lendo até o fim deste artigo.

Mas receio que esta seção talvez seja o fim!

Vamos conseguir obter as tipagens de cada tela da stack e a sua configuração com React.ComponentProps. E o resultado vai ser simplesmente incrível.

Veja abaixo o exemplo completo:

import { createStackNavigator } from "@react-navigation/stack";
import * as React from "react";
import { View } from "react-native";

type AppStackParamList = {
  Home: undefined;
  Notifications: undefined;
  Profile: undefined;
  Settings: undefined;
};

const Home = () => <View />;
const Notifications = () => <View />;
const Profile = () => <View />;
const Settings = () => <View />;

const Stack = createStackNavigator<AppStackParamList>();

const routes: Array<React.ComponentProps<typeof Stack.Screen>> = [
  {
    name: "Home",
    component: Home,
  },
  {
    name: "Notifications",
    component: Notifications,
  },
  {
    name: "Profile",
    component: Profile,
  },
  {
    name: "Settings",
    component: Settings,
  },
];

function AppStack() {
  return (
    <Stack.Navigator>
      {routes.map((routeConfig) => (
        <Stack.Screen key={routeConfig.name} {...routeConfig} />
      ))}
    </Stack.Navigator>
  );
}

E sim, ele continua com intellisense e continua avisando se você colocar na sua stack uma tela que não tem relação com ela (ou seja, uma tela que não está na declaração de tipo da sua stack), assim:

Tela inválidaTela inválida

O intellisense também vai estar lá:

Também fica mais limpo, configurável e dinâmico:

const getAuthStackRoutes = (
  // other parameters...
  theme: ThemeType
): Array<React.ComponentProps<typeof Stack.Screen>> => {
  // more business logic...

  return [
    {
      name: "Home",
      component: Home,
      options: {
        headerStyle: {
          backgroundColor: theme.colors.primary,
          // other theme stylings...
        },
      },
    },
  ];
};

Em resumo, essa abordagem permite gerenciar estruturas de navegação complexas com facilidade (pelo menos quando comparamos essa abordagem específica com as outras deste artigo). Isso porque, além de ter um JSX mais limpo, você também consegue configurar as suas rotas de um jeito mais dinâmico e modular.

Levando o uso de TypeScript um passo adiante

Não precisamos nos limitar a declarar só o tipo genérico do createStackNavigator. Que tal o tipo dos elementos filhos que o Stack.Navigator vai ter? Embora esse conceito já esteja muito bem definido na documentação oficial, vamos ver abaixo como podemos brincar com ele para ter uma forma mais desacoplada de criar a estrutura.

import type { RouteConfig, StackNavigationState } from "@react-navigation/core";
import {
  createStackNavigator,
  StackNavigationEventMap,
  StackNavigationOptions,
} from "@react-navigation/stack";
import * as React from "react";
import { View } from "react-native";

// stack param list type
type AppStackParamList = {
  Home: undefined;
  Notifications: undefined;
  Profile: undefined;
  Settings: undefined;
};

// type of the single route in app stack
type AppStackRoutesType = RouteConfig<
  AppStackParamList,
  keyof AppStackParamList,
  StackNavigationState<AppStackParamList>,
  StackNavigationOptions,
  StackNavigationEventMap
>;

// mocking the screen components for the sake of example
const Home = () => <View />;
const Notifications = () => <View />;
const Profile = () => <View />;
const Settings = () => <View />;

// strictly typed array of app stack routes
const appStackRoutes: Array<AppStackRoutesType> = [
  {
    name: "Home",
    component: Home,
  },
  {
    name: "Notifications",
    component: Notifications,
  },
  {
    name: "Profile",
    component: Profile,
  },
  {
    name: "Settings",
    component: Settings,
  },
];

const Stack = createStackNavigator<AppStackParamList>();

function AppStack() {
  return (
    <Stack.Navigator>
      {/** mapping the app stack routes */}
      {appStackRoutes.map((stackRoute) => (
        <Stack.Screen key={stackRoute.name} {...stackRoute} />
      ))}
    </Stack.Navigator>
  );
}

Opa, tem muita coisa acontecendo aqui… Vamos dividir cada bloco de código em partes separadas.

import type { RouteConfig, StackNavigationState } from "@react-navigation/core";
import {
  createStackNavigator,
  StackNavigationEventMap,
  StackNavigationOptions,
} from "@react-navigation/stack";
import * as React from "react";
import { View } from "react-native";

No topo do trecho de código, importamos os módulos necessários. Esses imports incluem types, funções e outras coisas necessárias. Não são interessantes, mas são necessários :)

// mocking the screen components for the sake of example
const Home = () => <View />;
const Notifications = () => <View />;
const Profile = () => <View />;
const Settings = () => <View />;

Acima, importamos o componente View do react-native para que o exemplo seja demonstrável de um jeito mais simples.

// type of the single route in app stack
type AppStackRoutesType = RouteConfig<
  AppStackParamList,
  keyof AppStackParamList,
  StackNavigationState<AppStackParamList>,
  StackNavigationOptions,
  StackNavigationEventMap
>;

Agora vem a parte interessante. O RouteConfig, importado de @react-navigation/core, recebe exatamente cinco tipos como tipo genérico. Essa definição de tipo específica não está documentada no site oficial do react-navigation, mas você já consegue descobri-la usando o método de pular para a definição de tipo que mencionamos acima.

Mesmo que pareça redundante ou desnecessário em um projeto react-native típico com typescript, isso traz vários benefícios, que serão explicados na seção abaixo.

IntelliSense

Como temos um array de rotas da stack (ou seja, rotas do app) com tipagem estrita, cada elemento do array agora é obrigado a seguir a definição de tipo do array. Isso significa que o IntelliSense funciona de cara ao adicionar um novo elemento ao array.

Além disso, aplicar esse tipo nos obriga a atualizar o AppStackRoutesType sempre que um novo elemento for adicionado às rotas do app. Caso contrário, não conseguiríamos adicionar um novo elemento que não existe no AppStackRoutesType (AppStackParamList).

Mapeando as rotas

Chegamos à última parte: criamos o stack navigator com createStackNavigator. Depois, é só questão de mapear o array que criamos acima junto com o seu tipo estrito.

Finalmente podemos confiar em cada elemento do nosso array, porque todos terão a tipagem correta. Por isso, é seguro usar a spread syntax.

const Stack = createStackNavigator<AppStackParamList>();

function AppStack() {
  return (
    <Stack.Navigator>
      {/** mapping the app stack routes */}
      {appStackRoutes.map((stackRoute) => (
        <Stack.Screen key={stackRoute.name} {...stackRoute} />
      ))}
    </Stack.Navigator>
  );
}

Era mesmo a última parte?

Bom… Não!

Ainda podemos melhorar as tipagens do exemplo que vimos.

// generic stack routes type
export type StackRoutesType<ParamList extends ParamListBase> = Array<
  RouteConfig<
    ParamList,
    keyof ParamList,
    StackNavigationState<ParamList>,
    StackNavigationOptions,
    StackNavigationEventMap
  >
>;

type AppStackRoutesType = StackRoutesType<AppStackParamList>;

// mocking the screen components for the sake of example
const Home = () => <View />;
const Notifications = () => <View />;
const Profile = () => <View />;
const Settings = () => <View />;

// strictly typed array of app stack routes
const appStackRoutes: AppStackRoutesType = [
  {
    name: "Home",
    component: Home,
  },
  {
    name: "Notifications",
    component: Notifications,
  },
  {
    name: "Profile",
    component: Profile,
  },
  {
    name: "Settings",
    component: Settings,
  },
];

A diferença que você talvez tenha notado é que temos o StackRoutesType, que recebe um tipo genérico e é igual ao tipo que já vimos antes. Mas qual é o benefício aqui, você pode perguntar. Melhor responder a essa pergunta de forma visual.

// too much duplicated code...

type AppStackRoutesType = RouteConfig<
  AppStackParamList,
  keyof AppStackParamList,
  StackNavigationState<AppStackParamList>,
  StackNavigationOptions,
  StackNavigationEventMap
>;

type OtherStackRoutesType = RouteConfig<
  OtherStackParamList,
  keyof OtherStackParamList,
  StackNavigationState<OtherStackParamList>,
  StackNavigationOptions,
  StackNavigationEventMap
>;

type AnotherStackRoutesType = RouteConfig<
  AnotherStackParamList,
  keyof AnotherStackParamList,
  StackNavigationState<AnotherStackParamList>,
  StackNavigationOptions,
  StackNavigationEventMap
>;

Se não usássemos o StackRoutesType genérico, teríamos que duplicar as tipagens para cada stack do app.

Isso viraria um pesadelo conforme o app cresce. (a ideia aqui é que o número de stacks no app e a complexidade do app são diretamente proporcionais. Na verdade, essa suposição nem sempre é 100% válida, mas serve para este exemplo específico)

// generic stack routes type
export type StackRoutesType<ParamList extends ParamListBase> = Array<
  RouteConfig<
    ParamList,
    keyof ParamList,
    StackNavigationState<ParamList>,
    StackNavigationOptions,
    StackNavigationEventMap
  >
>;

// becomes one line typings for each stack
type AppStackRoutesType = StackRoutesType<AppStackParamList>;
type OtherStackRoutesType = StackRoutesType<OtherStackParamList>;
type AnotherStackRoutesType = StackRoutesType<AnotherStackParamList>;

Por outro lado, veja acima como tudo fica mais simples e limpo agora usando o tipo genérico.

Resultado final

Vamos comparar como uma função Stack típica ficaria em dois cenários diferentes:

Imagem 1: Renderizando todas as telas da stack uma por uma no JSX.

// ...imports, components

function AppStack() {
  return (
    <Stack.Navigator>
      <Stack.Screen name="Home" component={Home} />
      <Stack.Screen name="Notifications" component={Notifications} />
      <Stack.Screen name="Profile" component={Profile} />
      <Stack.Screen name="Settings" component={Settings} />
      {/** n more screens... */}
    </Stack.Navigator>
  );
}

Imagem 2: Renderizando as telas com o array de rotas da stack criado com typescript de tipagem estrita. 🎉

function AppStack() {
  return (
    <Stack.Navigator>
      {appStackRoutes.map((stackRoute) => (
        <Stack.Screen key={stackRoute.name} {...stackRoute} />
      ))}
    </Stack.Navigator>
  );
}

Mais uma coisa… E as props do Navigator?

Talvez ainda falte considerar uma coisa: as props do stack navigator. Olhando o StackNavigator abaixo, existe um bloco de configurações para um único navigator. Por que não desacoplar essas configurações do JSX?

import type {
  DefaultNavigatorOptions,
  ParamListBase,
  StackNavigationState,
} from "@react-navigation/core";
import {
  StackNavigationEventMap,
  StackNavigationOptions,
} from "@react-navigation/stack";
// other necessary imports for screens...

// generic typing for stack navigator options
type StackNavigatorOptions<ParamList extends ParamListBase> =
  DefaultNavigatorOptions<
    ParamList,
    StackNavigationState<ParamList>,
    StackNavigationOptions,
    StackNavigationEventMap
  >;

// omit the children as it corresponds to stack screen
const appStackNavigatorProps: Omit<
  StackNavigatorOptions<AppStackParamList>,
  "children"
> = {
  initialRouteName: "Home",
  screenOptions: {
    headerShown: false,
    cardOverlayEnabled: true,
    gestureEnabled: false,
    cardStyle: {
      backgroundColor: "royalblue",
    },
    headerLeftContainerStyle: {
      backgroundColor: "firebrick",
    },
    presentation: "modal",
    headerTitleStyle: {
      fontSize: 24,
      color: "olivedrab",
    },
  },
  // ...rest
};

// screen components and stack routes...

function AppStack() {
  return (
    <Stack.Navigator {...appStackNavigatorProps}>
      {appStackRoutes.map((stackRoute) => (
        <Stack.Screen key={stackRoute.name} {...stackRoute} />
      ))}
    </Stack.Navigator>
  );
}

A partir da linha 13, já devemos estar familiarizados com o motivo de usarmos o tipo genérico. A pequena diferença de tipagem em relação às rotas da stack talvez seja o tipo DefaultNavigatorOptions, importado de @react-navigation/core. O próprio nome do tipo já se explica: são as opções do navigator.

Assim como o tipo RouteConfig que mencionamos acima, ele também recebe vários tipos genéricos. Além disso, lembre que estamos omitindo explicitamente a chave children, já que já estamos renderizando os children do Stack.Navigator, que correspondem ao Stack.Screen.

Na linha 22, criamos um objeto novinho (ou pode ser uma função, desde que retorne um objeto que satisfaça o tipo de opções do navigator) que vai representar as opções do nosso navigator.

Como resultado, na linha 50, esse objeto pode ser usado com segurança com a spread syntax, desde que satisfaça o tipo informado.

JSX muito mais limpo… Na minha opinião…

Resultado final: props do Navigator

Vamos comparar de novo como uma função Stack típica ficaria em dois cenários diferentes:

Imagem 1: Configurações do stack navigator dentro do JSX.

function AppStack() {
  return (
    <Stack.Navigator
      initialRouteName="Home"
      screenOptions={{
        headerShown: false,
        cardOverlayEnabled: true,
        gestureEnabled: false,
        cardStyle: {
          backgroundColor: "royalblue",
        },
        headerLeftContainerStyle: {
          backgroundColor: "firebrick",
        },
        presentation: "modal",
        headerTitleStyle: {
          fontSize: 24,
          color: "olivedrab",
        },
      }}
      // rest...
    >
      {appStackRoutes.map((stackRoute) => (
        <Stack.Screen key={stackRoute.name} {...stackRoute} />
      ))}
    </Stack.Navigator>
  );
}

Imagem 2: Configurações do stack navigator desacopladas do JSX.

// ...

function AppStack() {
  return (
    <Stack.Navigator {...appStackNavigatorProps}>
      {appStackRoutes.map((stackRoute) => (
        <Stack.Screen key={stackRoute.name} {...stackRoute} />
      ))}
    </Stack.Navigator>
  );
}

Conclusão

Neste artigo, vimos como realmente aproveitar o TypeScript e chegar a uma forma mais limpa de estruturar os navigators no react-native.

Tenham todos um dia sem bugs.

Publicado em

Este artigo também foi publicado em: