Deco
Pt

Páginas e rotas

Como URLs guiadas pelo CMS mapeiam para rotas TanStack Router via cmsRouteConfig.

Em v2, a maior parte das URLs de uma loja é guiada pelo CMS. O framework provê dois helpers que conectam o TanStack Router ao resolver do CMS, então você não precisa escrever código por URL para páginas de conteúdo.

As duas rotas obrigatórias

Catch-all: src/routes/$.tsx

Lida com toda URL não capturada por uma rota mais específica — PDPs, PLPs, páginas de conteúdo, busca, qualquer coisa que esteja em .deco/blocks/ .

 // exemplo mínimo
import { createFileRoute } from "@tanstack/react-router";
import { cmsRouteConfig, loadCmsPage } from "@decocms/start/routes";

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

Home: src/routes/index.tsx

Mesmo formato, para a raiz / :

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

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

O que os helpers realmente fazem

cmsRouteConfig retorna uma config TanStack Router com:

  • Um loader que chama loadCmsPage({ siteName, pathname, search }) para resolver o block da página e suas sections.
  • Uma função head que extrai o SEO da página resolvida.
  • Um pendingComponent que renderiza o shell enquanto carrega.
  • Um errorComponent que mostra erros de section.
  • Um component padrão que renderiza <DecoPageRenderer /> sobre os dados carregados.

Você pode sobrescrever qualquer um — passe seu próprio loader , validateSearch ou component e o framework faz o merge.

Opções importantes

ignoreSearchParams

Search params que não estão nessa lista entram na cache key. A seleção de variante usa ?skuId=... , o que causaria miss no cache em toda troca de SKU; coloque na lista para ignorar.

 ignoreSearchParams: ["skuId", "_branch"]

staleTime / gcTime

Tunning de cache do loader cache do TanStack Router (separado do edge cache).

 cmsRouteConfig({
  siteName: "minha-loja",
  staleTime: 30_000,
  gcTime: 5 * 60_000,
})

siteName

O identificador do site no admin. Tem que casar com o que está em admin.deco.cx .

Embrulhar com withSiteGlobals

Alguns sites precisam injetar loaders ou heads globais por cima da rota CMS. @decocms/start/routes exporta withSiteGlobals :

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

Isso injeta dados globais (analytics IDs, theme tokens etc.) em toda página sem ter que mexer em cada rota.

Rotas customizadas ao lado da catch-all

Você pode adicionar rotas específicas que têm precedência sobre $ :

 src/routes/
├── __root.tsx       # layout global
├── index.tsx        # cmsHomeRouteConfig
├── $.tsx            # cmsRouteConfig (catch-all)
├── api/
│   └── analytics.tsx   # POST handler, ganha do $
└── checkout/
    └── success.tsx     # página customizada de confirmação

TanStack Router resolve caminhos mais específicos primeiro, então qualquer arquivo explícito ganha da catch-all.

O root layout

src/routes/__root.tsx é onde mora o shell — <html> , <head> , fontes, providers. Dois padrões:

Usar DecoRootLayout

O shell que o framework provê cuida de fontes, preconnects e do iframe de preview do CMS:

 import { DecoRootLayout } from "@decocms/start/hooks";

export const Route = createRootRoute({
  component: () => (
    <DecoRootLayout
      account="minha-loja"
      head={[/* fontes, preconnects */]}
    />
  ),
});

Construir o seu

Descarte DecoRootLayout e escreva um __root.tsx do zero quando precisar de carregamento de fontes específico, drawer de minicart no shell, ou qualquer markup que os defaults do framework não conseguem expressar. Copie os providers que precisar de PreviewProviders e LiveControls (ambos de @decocms/start/hooks ).

Server functions e loaders

Dentro de qualquer rota, você pode usar createServerFn de @tanstack/react-start para lógica server-side arbitrária. O framework usa internamente para loadDeferredSection . Use também para endpoints específicos do site ao lado das rotas CMS.

Não coloque handlers de admin ( /live/_meta , /.decofile , /deco/render , /deco/invoke ) dentro de server entries do TanStack. O Vite remove lógica custom de createServerEntry em builds de produção. Rotas de admin têm que viver no worker-entry.ts via createDecoWorkerEntry . Veja Referência do worker entry.

Cache headers por rota

Detecção do profile de cache por padrão de URL é automática. Para sobrescrever por rota, defina headers na config da rota. O framework também expõe setCacheProfile e registerCachePattern para tunning global. Veja Estratégia de cache.

Veja também

Previous
Sections
Componentes React que o CMS posiciona em uma página.
Next

Found an error or want to improve this page?

Edit this page