Arquitetura Técnica: Construir um Comparador de Viagens com Next.js 14 e TypeScript Strict

Introdução: Por que uma Stack Técnica Rigorosa para Viagens

No setor de turismo online, a confiabilidade dos dados é tão crucial quanto a rapidez de exibição. Um comparador de viagens manipula fluxos complexos: horários de trens, preços dinâmicos, disponibilidades em tempo real e múltiplas moedas. Um erro de tipo no código pode se traduzir em uma passagem vendida por um preço errado ou um horário incorreto, o que é inaceitável para o usuário final.

É por isso que, para a reformulação de nossa plataforma em 2026, optamos por uma arquitetura baseada em Next.js 14 com o App Router, acoplada a uma configuração TypeScript em modo strict. Essa combinação nos permite aproveitar os benefícios da renderização no servidor (Server Components) para SEO, ao mesmo tempo que impõe uma segurança de tipagem que reduz drasticamente os bugs em produção. De acordo com a documentação oficial do Next.js, o App Router representa a evolução fundamental para o gerenciamento de rotas e layouts, permitindo uma granularidade fina no cache e no streaming de dados.

Neste artigo, detalharemos as escolhas técnicas que sustentam nosso comparador, focando na configuração do TypeScript, no gerenciamento de dados via Server Actions e na otimização das Core Web Vitals.

Next.js 14 e o App Router: O Coração do Sistema

A adoção do App Router no Next.js 14 marca uma mudança de paradigma em relação ao histórico Pages Router. Para um comparador de viagens, onde a estrutura das páginas é hierárquica (Início > Destino > Transporte > Detalhe), o sistema de roteamento baseado no sistema de arquivos do App Router oferece uma clareza indispensável.

Server Components por Padrão

Uma das principais vantagens é o uso dos React Server Components (RSC) por padrão. Em nosso comparador, as listas de resultados de busca (trens, ônibus, voos) são renderizadas no servidor. Isso significa que o código de busca de dados é executado diretamente no servidor, perto do banco de dados ou das APIs de terceiros (SNCF, DB, Eurail). Isso elimina a necessidade de um estado de carregamento visível pelo usuário para o conteúdo inicial e melhora o Largest Contentful Paint (LCP), uma métrica chave das Core Web Vitals definida pelo Google.

Ao contrário das abordagens anteriores onde o cliente precisava buscar os dados via useEffect, agora usamos componentes assíncronos diretamente na hierarquia de rotas. Aqui está um exemplo simplificado de nossa página de resultados:

// app/search/results/page.tsx
import { searchTrips } from '@/lib/api';
import { TripList } from './trip-list';

export default async function SearchResults({ searchParams }: { searchParams: { from: string; to: string } }) {
  const trips = await searchTrips(searchParams.from, searchParams.to);
  
  return (
    <main>
      <h1>Resultados para {searchParams.from} até {searchParams.to}</h1>
      <TripList trips={trips} />
    </main>
  );
}

Essa abordagem reduz o bundle JavaScript enviado ao cliente, pois a lógica de fetch não está incluída no código baixado pelo navegador. Para um usuário em uma rede móvel durante uma viagem, essa economia de dados e tempo de processamento é significativa.

Gerenciamento de Layouts Aninhados

A estrutura de nossa aplicação requer layouts persistentes, como a barra de navegação e o rodapé, que não devem recarregar durante a navegação entre as páginas de resultados. O App Router gerencia isso nativamente via arquivo layout.tsx. Além disso, podemos ter layouts específicos para certas seções, como a seção "Nightjet" ou "Eurail", permitindo injetar scripts ou estilos específicos sem afetar o resto da aplicação.

TypeScript Strict: Uma Segurança Indispensável

Usar TypeScript é uma coisa, usá-lo em modo strict é outra. Em nosso tsconfig.json, ativamos todas as opções de strictness. Isso inclui noImplicitAny, strictNullChecks e strictFunctionTypes. Para um comparador que agrega dados provenientes de múltiplas APIs heterogêneas, a segurança de tipos é nossa primeira linha de defesa.

Configuração tsconfig.json

Aqui está a base de nossa configuração TypeScript, alinhada com as recomendações de 2026 para projetos enterprise:

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [{ "name": "next" }]
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

A opção strict: true força o desenvolvedor a gerenciar explicitamente os casos onde uma variável pode ser undefined ou null. No contexto de viagens, um preço pode ser nulo (oferta gratuita), um horário de partida pode estar faltando (trajeto incompleto). O TypeScript nos obriga a gerenciar esses casos explicitamente, evitando erros clássicos do tipo Cannot read property of undefined.

Tipagem de Variáveis de Ambiente

Um erro comum em projetos Next.js é o uso não tipado de variáveis de ambiente. Usamos uma biblioteca como t3-env ou um schema Zod personalizado para validar as variáveis na inicialização do servidor. Isso garante que, se uma chave API para um fornecedor de trem (ex: API DB ou SNCF) estiver faltando, a aplicação se recusa a iniciar em vez de falhar silenciosamente em produção.

// env.ts
import { createEnv } from "@t3-oss/env-nextjs";
import { z } from "zod";

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
    RAIL_API_KEY: z.string().min(1),
  },
  client: {
    NEXT_PUBLIC_ANALYTICS_ID: z.string().min(1),
  },
  runtimeEnv: {
    DATABASE_URL: process.env.DATABASE_URL,
    RAIL_API_KEY: process.env.RAIL_API_KEY,
    NEXT_PUBLIC_ANALYTICS_ID: process.env.NEXT_PUBLIC_ANALYTICS_ID,
  },
});

Essa prática, recomendada pela comunidade Vercel e pelos mantenedores do Next.js, garante que nossa configuração seja tão robusta quanto nosso código.

Validação de Dados com Zod e Server Actions

Em uma arquitetura App Router, as Server Actions frequentemente substituem as API Routes tradicionais para mutações de dados (como reserva ou salvamento de um alerta de preço). No entanto, os argumentos passados para uma Server Action não são tipados por padrão durante a chamada do cliente. É aqui que a validação de schema se torna crítica.

Usamos Zod para validar as entradas do usuário antes de qualquer processamento de negócio. Isso protege contra injeções e dados malformados. Por exemplo, ao buscar uma viagem, precisamos garantir que as datas sejam válidas e que os códigos das estações existam.

Exemplo de Server Action Tipada

// actions/search.ts
'use server';

import { z } from 'zod';
import { db } from '@/lib/db';

const SearchSchema = z.object({
  origin: z.string().length(3), // Código IATA ou UIC
  destination: z.string().length(3),
  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
  passengers: z.number().min(1).max(9),
});

export async function searchTrip(formData: FormData) {
  const rawData = {
    origin: formData.get('origin'),
    destination: formData.get('destination'),
    date: formData.get('date'),
    passengers: Number(formData.get('passengers')),
  };

  const result = SearchSchema.safeParse(rawData);

  if (!result.success) {
    return { error: 'Dados inválidos', details: result.error.flatten() };
  }

  // Processamento de negócio seguro
  const trips = await db.trip.findMany({
    where: {
      origin: result.data.origin,
      // ... outros filtros
    }
  });

  return { success: true, data: trips };
}

Combinando TypeScript strict e Zod, obtemos uma validação estática (na compilação) e dinâmica (na execução). É o que chamamos de "type safety end-to-end". De acordo com as boas práticas TypeScript 2026, essa dupla validação é essencial para aplicações críticas.

Performance e SEO: Os Desafios do Comparador

Um comparador de viagens vive por seu referenciamento orgânico (SEO). Os usuários buscam "Trem Paris Berlin" ou "Nightjet Bruxelas". O Next.js 14 se destaca nessa área graças à geração de site estático (Static Site Generation) e à renderização dinâmica híbrida.

Otimização de Imagens e Fontes

Usamos o componente next/image para otimizar automaticamente os visuais dos trens e destinos. Isso permite servir formatos modernos como WebP ou AVIF dependendo do navegador do usuário. Além disso, o uso de next/font para carregar fontes (como Inter ou Roboto) elimina o layout shift (CLS), garantindo que o texto não se mova durante o carregamento.

Streaming e Suspense

Para páginas de resultados complexas, usamos React Suspense. Isso permite exibir imediatamente o esqueleto da página (cabeçalho, filtros) enquanto os resultados da busca, que podem levar alguns segundos para agregar desde vários fornecedores (Ouigo, TGV Inoui, DB), carregam em segundo plano. O usuário pode começar a interagir com os filtros antes mesmo que a lista completa de trens seja exibida.

Essa técnica melhora consideravelmente o Time to Interactive (TTI). Em um contexto competitivo onde cada segundo conta para a conversão, essa otimização técnica se traduz diretamente em um aumento na taxa de reserva.

Internacionalização (i18n) e Manutenção

Nosso comparador visa um público europeu. O gerenciamento de vários idiomas (francês, alemão, inglês, espanhol) é nativo em nossa estrutura de rotas. O Next.js permite prefixar as rotas pela locale (/fr/search, /de/search).

Com TypeScript, tipamos as chaves de tradução. Isso significa que, se um desenvolvedor adiciona um novo texto na interface mas esquece de atualizar o arquivo de tradução alemão, o compilador levantará um erro. Isso evita situações embaraçosas onde uma parte da interface permanece em inglês em uma página destinada ao mercado alemão.

A manutenção do código também é facilitada pela modularidade do App Router. Cada funcionalidade (busca, pagamento, conta de usuário) é isolada em sua própria pasta com seus próprios testes. Usamos Vitest para testes unitários e Playwright para testes end-to-end, garantindo que atualizações de dependências (como a migração para React 19 prevista no ecossistema Next.js) não quebrem funcionalidades existentes.

Conclusão: Uma Base Sólida para o Futuro

A escolha do Next.js 14 e do TypeScript strict não é apenas uma tendência técnica, é uma necessidade operacional para um comparador de viagens em 2026. A complexidade dos dados ferroviários e aéreos exige um rigor que a tipagem estática impõe naturalmente. O App Router oferece a flexibilidade necessária para compor interfaces ricas mantendo performances de primeira ordem.

Seguindo as recomendações da documentação do Next.js e aplicando padrões stricts de qualidade de código, construímos uma plataforma capaz de evoluir. Seja para integrar novos fornecedores como as linhas Nightjet estendidas ou para suportar novas regulamentações europeias sobre dados de viajantes, nossa arquitetura está pronta. A técnica serve aqui a experiência do usuário: um site mais rápido, mais confiável e mais seguro para preparar suas próximas viagens pela Europa.

Para ir além, recomendamos consultar a documentação oficial do Next.js sobre o App Router e o guia de configuração TypeScript para atualizações regulares sobre as melhores práticas emergentes.