TanStack Start: primeiros passos

O pessoal do TanStack lançou um framework novo chamado TanStack Start. É basicamente um concorrente direto do Next, um framework full stack pra React.

Vou comentar algumas coisas conforme a gente for testando, com o objetivo de te passar uma visão geral sobre ele.

O TanStack Start usa o TanStack Router por baixo dos panos. O time do TanStack tem várias bibliotecas diferentes (Router, Query e outras), o que também gera uma diversificação grande de ferramentas pra escolher.

Criando o projeto

Pra criar um projeto novo:

npm create tanstack@latest

O assistente de criação vai perguntar várias coisas: nome do projeto, se você quer usar Tailwind, se quer algum linter (Biome ou ESLint), e se quer já integrar serviços prontos como Clerk (autenticação), Convex, Neon (banco de dados), Sentry (observabilidade), entre outros. Dá pra deixar tudo isso de lado no começo e ir adicionando depois.

Depois de criado, é só entrar na pasta e rodar:

npm run dev

O projeto sobe com Vite, na porta 3000, com uma tela padrão de boas-vindas.

Como funciona o roteamento

O roteamento do TanStack Start é baseado em arquivos, só que de um jeito um pouco diferente do Next. Aqui, dentro do próprio arquivo da rota, você configura o comportamento dela com uma função chamada createFileRoute.

export const Route = createFileRoute("/")({
  component: Home,
});

Existe também um arquivo de rota raiz, o __root, que funciona como uma configuração geral pra todas as páginas: meta tags, título, CSS global e o layout (HTML, head, header, etc). É meio parecido com o layout.tsx do Next, só que junto com a configuração do próprio router.

Client first, diferente do Next

Uma diferença importante de filosofia: o TanStack Start segue o comportamento padrão do React, que é client first. Ou seja, por padrão os componentes rodam no cliente, e você decide o que roda no servidor.

O Next é o oposto: os componentes são server component por padrão, e você usa "use client" quando quer rodar algo no navegador. Se você já tem experiência com Next, essa é a principal mudança de mentalidade ao migrar pra cá.

Server functions, não server components

O TanStack Start ainda não suporta server components. O que ele tem são server functions, o equivalente às server actions do React/Next: funções que você marca pra rodar no servidor.

export const getPosts = createServerFn({ method: "GET" }).handler(async () => {
  return readPosts();
});

Você cria a função com createServerFn, define o método (GET, POST, etc) e passa um handler, que é a função de verdade que vai executar.

Loader: carregando dados antes de renderizar

Um dos recursos mais interessantes é o loader. Ele é uma função que roda antes do componente da rota ser renderizado, buscando os dados necessários pra tela.

export const Route = createFileRoute("/blog")({
  loader: () => getPosts(),
  component: Blog,
});
 
function Blog() {
  const posts = Route.useLoaderData();
 
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

Como o loader roda antes da página abrir, quando o componente é renderizado os dados já estão disponíveis. Não existe aquele momento de tela vazia com loading pra depois carregar o conteúdo, como acontece quando você busca dados só no cliente.

Organizando o código

Pra não deixar tudo espremido no mesmo arquivo de rota, dá pra separar em camadas: uma pasta functions com as server functions, uma pasta services com as funções puras que fazem a requisição de fato, e uma pasta types com os tipos. Assim a rota só chama a server function, a server function chama o service, e cada peça fica isolada.

Vale a pena testar?

O TanStack Start é um framework promissor, com bastante recurso interessante: server side rendering, streaming, DevTools próprio pra debugar as rotas. SEO também é tratado, não é motivo pra descartar o framework.

Se você já manja de Next, o principal ajuste de cabeça é lembrar que aqui o padrão é client first, e que server function não é a mesma coisa que server component.