Ir para o conteúdo
decodecodeveloper docs
Storefront → Templates → Commerce

Shopify

Configure Shopify em um storefront Blocks 7.x e conecte produtos, carrinho e clientes no servidor.

@decocms/apps-shopify conecta um site Blocks 7.x publicado à Storefront API da Shopify. Fornece loaders e actions no servidor. O storefront implementa sua UI React e funções de servidor; o Site Editor edita a configuração salva do app.

Configure block

Defina o subdomínio Shopify e a URL pública do storefront:

.deco/blocks/deco-shopify.json
{
  "__resolveType": "deco-shopify",
  "storeName": "my-shop",
  "publicUrl": "https://my-shop.example.com"
}

Guarde SHOPIFY_STOREFRONT_TOKEN no ambiente do servidor. No Workers, use wrangler secret put SHOPIFY_STOREFRONT_TOKEN. A autoconfiguração usa essa variável quando o token não está salvo e também resolve o formato de secret criptografado da integração. Mantenha secrets fora de campos públicos comuns.

Wiring no setup

Depois de o setup carregar o decofile, execute este módulo apenas no servidor:

src/setup/apps.ts
import { autoconfigApps, type AppRegistry } from "@decocms/blocks-admin/apps";
import { loadBlocks } from "@decocms/blocks/cms";
import { SHOPIFY_REGISTRY_ENTRY } from "@decocms/apps-shopify/registry";
import * as shopifyMod from "@decocms/apps-shopify/mod";
 
const APP_REGISTRY: AppRegistry = [
  { ...SHOPIFY_REGISTRY_ENTRY, module: async () => shopifyMod },
];
 
await autoconfigApps(loadBlocks(), APP_REGISTRY);

Não há registro combinado padrão. Passe explicitamente o mapa de blocos e o registro. A alternativa initShopifyFromBlocks(blocks) aceita um token em texto e configura uma vez por processo; ela não descriptografa um objeto de secret nem lê o fallback de ambiente. Para esses casos, use o registro acima.

Cliente

Ative o fetch instrumentado uma vez no setup do servidor:

import { setShopifyFetch, createShopifyFetch } from "@decocms/apps-shopify";
 
setShopifyFetch(createShopifyFetch());

O cliente do pacote fixa a versão da Storefront API. Ele não oferece cache de respostas do provedor; envolva loaders de leitura com o helper de cache quando necessário.

Loaders disponíveis

Chame as funções exportadas passando a URL real da página:

import { productDetailsPageLoader, productListingPageLoader } from "@decocms/apps-shopify";
 
const url = new URL("https://my-shop.example.com/collections/summer");
const product = await productDetailsPageLoader({ slug: "blue-widget" }, url);
const listing = await productListingPageLoader({ collectionName: "summer", count: 24 }, url);

ProductListingPage atende coleções e busca; não existe loader separado SearchPage. O conteúdo pode referenciar loaders registrados como shopify/loaders/ProductDetailsPage e shopify/loaders/ProductListingPage. Na resolução de CMS, use o wrapper de URL quando parâmetros e links precisarem da requisição real.

Gotcha — cookie de carrinho

O loader do carrinho é getCart, de @decocms/apps-shopify/loaders/cart. Lê o cookie dos headers da requisição; quando recebe headers de resposta, pode criar o carrinho e gravar seu cookie. Encaminhe esses headers ao browser.

Criar um cookie não altera os headers da requisição recebida. Para adicionar itens nessa mesma requisição, a action precisa receber headers contendo o ID do carrinho criado. Siga o fluxo de carrinho e clientes.

Actions disponíveis

Actions de carrinho são exportadas por @decocms/apps-shopify/actions/cart; as de clientes ficam em actions/user/. Recebem os headers indicados por suas assinaturas. Use os nomes e entradas de 7.x, em vez de chaves antigas como actions/customer/login ou loaders/Account.

Hooks faltando

O pacote não inclui hooks React Shopify nem middleware de requisição. Implemente a UI sobre funções de servidor do storefront. Bindings de invoke gerados atendem handlers registrados; uma chave inventada shopify/loaders/Cart.ts não cria um endpoint de carrinho.

Tipos

Use os tipos de commerce e utilitários de transformação descritos no guia da integração. A API pública corresponde aos exports do pacote.

Pegadinhas

Shopify usa Storefront GraphQL e seus cookies de carrinho e cliente. Middleware, regras de região e hooks VTEX não se aplicam à Shopify. Cache e observabilidade do framework são separados do cliente do provedor.

Os recursos dependem da versão instalada. Confira o contrato 7.x antes de criar um hook ou action e valide produto, busca, carrinho e login na sua loja.

Veja também