Começar do zero

Esta página leva você do zero até uma loja v2 em produção, criando à mão o conjunto mínimo de arquivos que @decocms/start e @decocms/apps precisam para subir.

1. Crie o projeto

 mkdir minha-loja && cd minha-loja
npm init -y
git init 

2. Instale as dependências

 npm install \
  @decocms/start \
  @decocms/apps \
  @tanstack/react-start @tanstack/react-router \
  react@^19 react-dom@^19

npm install -D \
  vite@^6 \
  wrangler@^4 \
  typescript \
  @cloudflare/workers-types 

Os dois pacotes deco têm versões independentes. Fixe nas versões mais recentes publicadas:

• @decocms/start ^2.x — framework + ponte para o CMS.
• @decocms/apps ^1.x — integrações de commerce (VTEX, Shopify, Resend).

3. Adicione os arquivos de build

vite.config.ts :

 import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";
import { decoVitePlugin } from "@decocms/start/sdk/vitePlugin";

export default defineConfig({
  plugins: [
    cloudflare(),
    tanstackStart({ target: "cloudflare-module" }),
    react(),
    tailwindcss(),
    decoVitePlugin(),
  ],
}); 

wrangler.jsonc :

 {
  "name": "minha-loja",
  "main": "./src/worker-entry.ts",
  "compatibility_date": "2026-02-14",
  "compatibility_flags": ["nodejs_compat", "no_handle_cross_request_promise_resolution"]
} 

4. Conecte o framework

src/setup.ts — a configuração central. Precisa rodar antes de qualquer módulo importar suas sections, loaders ou matchers:

 import { createSiteSetup } from "@decocms/start/setup";
import { autoconfigApps } from "@decocms/start/apps";

export const setup = createSiteSetup({
  siteName: "minha-loja",
  sectionsGlob: import.meta.glob("./sections/**/*.tsx", { eager: true }),
  apps: autoconfigApps(),
}); 

src/worker-entry.ts — a camada mais externa do Worker. import "./setup" precisa ser a primeiríssima linha:

 import "./setup";

import { createDecoWorkerEntry } from "@decocms/start/sdk/workerEntry";
import {
  handleMeta,
  handleDecofile,
  handleRender,
  handleInvoke,
} from "@decocms/start/admin";
import serverEntry from "./server";

export default createDecoWorkerEntry(serverEntry, {
  admin: { handleMeta, handleDecofile, handleRender, handleInvoke },
}); 

src/server.ts — o server entry do TanStack Start. Também importa ./setup primeiro:

 import "./setup";
import { createServerEntry } from "@tanstack/react-start/server";
import { createRouter } from "./router";

export default createServerEntry({ createRouter }); 

5. Adicione as rotas do CMS

src/routes/__root.tsx — o shell global:

 import { DecoRootLayout } from "@decocms/start/hooks";
import { createRootRouteWithContext, Outlet } from "@tanstack/react-router";

export const Route = createRootRouteWithContext()({
  component: () => (
    <DecoRootLayout>
      <Outlet />
    </DecoRootLayout>
  ),
}); 

src/routes/index.tsx — a homepage, plugada no CMS:

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

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

src/routes/$.tsx — o catch-all para todas as outras URLs do CMS:

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

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

src/router.ts — conecta a route tree gerada pelo TanStack Router:

 import { createRouter as createTanStackRouter } from "@tanstack/react-router";
import { routeTree } from "./routeTree.gen";

export const createRouter = () =>
  createTanStackRouter({ routeTree }); 

6. Conecte ao CMS

Cada site precisa do seu próprio siteName e do conteúdo em .deco/blocks/ . O CMS guarda o conteúdo em dois lugares:

1. .deco/blocks/*.json — fonte da verdade, commitada. Edite via admin.deco.cx , sincronize para disco com o daemon.
2. src/server/cms/blocks.gen.json — bundle gerado que o framework carrega em runtime.

Provisione o site no admin.deco.cx , aponte para o seu dev server local com o daemon e puxe o conteúdo inicial em .deco/blocks/ . Em seguida gere o bundle pela primeira vez:

 npx deco generate-blocks 

(O nome do comando e o wiring exato ainda estão estabilizando; consulte a referência do framework para os scripts atuais.)

7. Configure commerce (opcional)

Se sua loja usa VTEX ou Shopify, configure o block correspondente no admin (ou direto em .deco/blocks/ ).

• VTEX — precisa de account mais os secrets appKey / appToken .
• Shopify — precisa de storeName mais um Storefront access token.

Veja Visão geral de commerce.

8. Rode o dev server

 npx vite dev 

O Vite serve a loja em http://localhost:5173 (ou qualquer PORT que você configure). A primeira requisição dispara o tunnel do daemon que mantém admin.deco.cx em sincronia com seu site local.

9. Deploy no Cloudflare Workers

 npx vite build
npx wrangler deploy 

Configure secrets via wrangler secret put ou pelo painel do Cloudflare. Veja Deployment no Cloudflare Workers para bindings de KV, observabilidade e checklists de produção.

O que vem pronto

Plugando os arquivos acima você ganha:

• O pipeline de build Vite + Cloudflare + TanStack Start.
• Um Worker entry com rotas do admin e cache de borda.
• O setup do site com glob de sections, blocks, matchers e init de plataforma.
• Uma rota catch-all + home via cmsRouteConfig / cmsHomeRouteConfig .
• Os arquivos gerados blocks.gen.ts , sections.gen.ts , meta.gen.json , loaders.gen.ts (após o primeiro generate).

A partir daí, é trocar peça por peça no seu ritmo.

Veja também

• Estrutura do projeto
• Visão geral da stack
• Migrar do v1
• Deployment no Cloudflare Workers