Routes

@decocms/start/routes expõe os helpers que conectam o TanStack Router ao resolver do CMS. Você toca em três arquivos: src/routes/$.tsx (catch-all), src/routes/index.tsx (home) e ocasionalmente src/routes/__root.tsx (shell global).

Import

 import {
  cmsRouteConfig,
  cmsHomeRouteConfig,
  loadCmsPage,
  loadDeferredSection,
  withSiteGlobals,
} from "@decocms/start/routes"; 

cmsRouteConfig

Constrói uma config TanStack Router para uma rota catch-all do CMS.

 // src/routes/$.tsx
import { createFileRoute } from "@tanstack/react-router";
import { cmsRouteConfig } from "@decocms/start/routes";

export const Route = createFileRoute("/$")(
  cmsRouteConfig({
    siteName: "minha-loja",
    defaultTitle: "Minha Loja",
    ignoreSearchParams: ["skuId"],
  }),
); 

Opções

 type CmsRouteOptions = {
  siteName: string;
  defaultTitle?: string;
  ignoreSearchParams?: string[];
  staleTime?: number;          // ms
  gcTime?: number;             // ms
  pendingComponent?: React.ComponentType;
  errorComponent?: React.ComponentType<{ error: Error }>;
}; 

O que retorna

Um objeto de config TanStack Router com:

• loader — chama loadCmsPage({ siteName, pathname, search }) .
• head — extrai SEO da página resolvida.
• component — <DecoPageRenderer /> sobre os dados carregados.
• pendingComponent — skeleton padrão, sobrescrevível.
• errorComponent — fallback padrão, sobrescrevível.

Você pode espalhar para sobrescrever pedaços:

 const config = cmsRouteConfig({ siteName: "minha-loja" });

export const Route = createFileRoute("/$")({
  ...config,
  component: function CustomPage() {
    return <CustomShell><DecoPageRenderer /></CustomShell>;
  },
}); 

cmsHomeRouteConfig

Mesmo formato que cmsRouteConfig , mas amarrado a / :

 // src/routes/index.tsx
import { createFileRoute } from "@tanstack/react-router";
import { cmsHomeRouteConfig } from "@decocms/start/routes";

export const Route = createFileRoute("/")(
  cmsHomeRouteConfig({ siteName: "minha-loja" }),
); 

A rota home pode ter cache e SEO defaults diferentes da catch-all (cache mais agressivo já que / raramente varia).

loadCmsPage

A função que o loader da rota chama. Você raramente chama direto, mas a assinatura ajuda a entender:

 loadCmsPage({
  siteName: string;
  pathname: string;
  search?: string | URLSearchParams;
}): Promise<ResolvedPage>; 

ResolvedPage é a árvore de sections resolvidas, pronta para o DecoPageRenderer .

loadDeferredSection

Server function do TanStack Start exposta pelo framework para sections deferred hidratarem ao rolar.

 // dentro do LazySection (você normalmente não chama direto)
loadDeferredSection({ pageId: string, sectionIndex: number }): Promise<RenderedSection>; 

O framework pluga LazySection com IntersectionObserver para chamar isso. Toque só se construir deferral custom.

withSiteGlobals

Embrulha uma config de rota com globais do site (analytics IDs, theme tokens, head tags custom).

 const routeConfig = withSiteGlobals(
  cmsRouteConfig({
    siteName: "minha-loja",
    defaultTitle: "Minha Loja",
    ignoreSearchParams: ["skuId"],
  }),
); 

Útil quando você quer adicionar as mesmas head tags em toda página CMS sem copiar a config em index.tsx e $.tsx .

Rotas custom ao lado da catch-all

Você pode adicionar rotas específicas que ganham da $.tsx :

 src/routes/
├── __root.tsx
├── index.tsx          ← cmsHomeRouteConfig
├── $.tsx              ← cmsRouteConfig (catch-all)
├── checkout/
│   └── success.tsx    ← página customizada
└── api/
    └── ping.tsx       ← endpoint API não-CMS 

TanStack Router despacha o caminho mais específico primeiro; /checkout/success e /api/ping viram seus arquivos, todo o resto cai na catch-all.

Server functions

Dentro de qualquer rota, createServerFn de @tanstack/react-start para lógica server arbitrária:

 import { createServerFn } from "@tanstack/react-start";

const updateCart = createServerFn("POST", async (input: CartInput) => {
  return await persistCart(input);
}); 

Ficam empacotadas como server functions automaticamente.

pendingComponent custom

O default é skeleton genérico. Sobrescreva por rota para experiência melhor:

 const config = cmsRouteConfig({ siteName: "minha-loja" });

export const Route = createFileRoute("/$")({
  ...config,
  pendingComponent: function PageSkeleton() {
    return (
      <div class="animate-pulse">
        <div class="h-12 bg-gray-200 mb-4" />
        <div class="grid grid-cols-4 gap-4">
          {[...Array(8)].map((_, i) => (
            <div key={i} class="aspect-square bg-gray-200" />
          ))}
        </div>
      </div>
    );
  },
}); 

Cache headers por rota

Defina headers na config da rota para sobrescrever o profile default:

 const config = cmsRouteConfig({
  siteName: "minha-loja",
  headers: () => ({
    "cache-control": "public, max-age=300, s-maxage=600",
  }),
}); 

Para overrides por padrão de URL, use setCacheProfile e registerCachePattern . Veja Estratégia de cache.

Veja também

• Páginas e rotas (conceito)
• Worker entry
• Hooks
• Caching