demo store

Loja de demonstração da camada de comércio

Esta Demo Store é uma solução de comércio eletrônico completamente estática (com capacidade SSR) desenvolvida pela Commerce Layer. A loja é completa e totalmente operacional, sem necessidade de serviços de terceiros. Você pode facilmente personalizar o seu próprio com diferentes níveis de personalização. Continue lendo para saber mais.

O projeto Demo Store consiste em dois repositórios, este é o modelo GitHub.

O que é camada de comércio?

Commerce Layer é uma API de comércio multimercado e sistema de gerenciamento de pedidos que permite adicionar recursos de compras globais a qualquer site, aplicativo móvel, chatbot, wearable, voz ou dispositivo IoT, com facilidade. Componha sua pilha com as melhores ferramentas que você já domina e adora. Torne qualquer experiência comprável, em qualquer lugar, por meio de uma API extremamente rápida, de nível empresarial e segura.

Índice

• Características
• Como funciona
• Começando
• Personalização
• Implantar
• Precisar de ajuda?
• Solução de problemas
• Licença

Características

Decidimos construir a Demo Store removendo todos os serviços de terceiros que normalmente são usados ​​para criar uma experiência abrangente em um site de comércio eletrônico (CMS, pesquisa, PIM, etc.).

Tudo relacionado ao conteúdo é armazenado como arquivos JSON. Para construir sua própria Demo Store você precisará criar esses arquivos manualmente ou por meio de scripts.

A Loja de Demonstração vem com:

• um mecanismo de pesquisa integrado com pesquisa de facetas desenvolvido por fuse.js
• um gerenciamento completo do catálogo de produtos com taxonomias e táxons
• gerenciamento de variantes de produto único
• recursos multilíngues para facilitar as vendas internacionalmente
• todo o extenso conjunto de recursos fornecidos imediatamente pelas APIs da camada de comércio (listas de preços em várias moedas, modelos de estoque que suportam vários locais de estoque e estratégias de atendimento, gateways de pagamento específicos do mercado, opções de entrega e contas de operadora, etc.)

A integração com o Commerce Layer é obtida aproveitando algumas de nossas ferramentas de código aberto para desenvolvedores, especificamente:

• a biblioteca JS Auth
• o SDK Javascript
• os componentes do React
• o carrinho hospedado
• o check-out hospedado

Como funciona

O projeto Demo Store consiste em dois repositórios que você pode aproveitar para construir sua própria loja, com base na quantidade de personalização que você precisa adicionar:

• demo-store

  Este é um modelo GitHub que usa o demo-store-core mencionado abaixo como um submódulo git. Se você estiver satisfeito com os recursos e a aparência da Commerce Layer Demo Store, sugerimos que você siga este caminho. Você não terá que se preocupar com todo o código-fonte e estará livre para se concentrar apenas nos seus dados e conteúdo. Além disso, você obterá atualizações gratuitas quase sem risco apenas executando:

  git submodule update --remote
  npm install

• demo-store-core

  Este repositório contém o código-fonte. Se você precisar personalizar totalmente sua loja (comportamento, UI, UX, etc.), basta fazer um fork deste repositório e criar o seu próprio. Essa também é a forma de contribuir.

  ️ Observe que se você seguir esse caminho e começar a divergir muito do código-fonte original, o risco é perder todas as atualizações futuras ou não conseguir replicá-las.

Começando

Se você não tem experiência com Commerce Layer, pode começar criando uma conta (é grátis!) e seguindo o tutorial de integração.

Importante

Observe que para configurar uma Demo Store você precisa de uma organização devidamente configurada com pelo menos alguns produtos e um mercado.

Se preferir começar do zero, você pode criar uma nova organização e usar os seguintes comandos para configurar um projeto semelhante ao Demo Store do Commerce Layer.

Configurando sua organização

Depois que a organização for criada, você precisa criar dois clientes API: um canal de vendas e um de integração .

Se ainda não o fez, instale o Commerce Layer CLI e dois de seus plug-ins: o plug-in seeder e o plug-in de importação:

npm install -g @commercelayer/cli

commercelayer plugins:install seeder
commercelayer plugins:install imports

Agora você pode fazer login no cliente da API de integração a partir da CLI:

commercelayer applications:login 
  --clientId Oy5F2TbPYhOZsxy1tQd9ZVZ... 
  --clientSecret 1ZHNJUgn_1lh1mel06gGDqa... 
  --organization my-awesome-organization 
  --alias cli-admin

Construindo sua loja

Depois que sua organização estiver configurada, para construir sua loja você precisa seguir alguns passos simples... vamos começar!

1. Crie um novo repositório

Seja qual for o caminho que você escolher, antes de mais nada, você precisa criar um novo repositório para sua loja:

• Se você decidiu manter o modelo demo-store basta clicar em "Usar este modelo" na página inicial do repositório no GitHub e executar:

  git clone < your-repository-url > my-new-project
  cd my-new-project
  git submodule update --init
  npm install
  
  cp ./demo-store-core/packages/website/.env.sample.submodule .env.local
  
  cp -r ./demo-store-core/packages/website/data/json ./data/json

• Se você decidiu bifurcar o repositório demo-store-core você pode executar isto:

  git clone < your-repository-url > my-new-project
  cd my-new-project
  npm install
  
  cp ./packages/website/.env.sample ./packages/website/.env.local

2. Defina as variáveis ​​de ambiente

Edite .env.local e preencha todas as informações que faltam:

 # this is the 'sales channel' client id
NEXT_PUBLIC_CL_CLIENT_ID =er34TWFcd24RFI8KJ52Ws6q...

3. Semeie os dados

Esta etapa é opcional. Se você já tiver uma organização configurada corretamente em sua conta do Commerce Layer, poderá ignorá-la.

O script a seguir preencherá sua organização com todos os recursos necessários para construir um comércio eletrônico multimercado com Commerce Layer (aqueles que estamos usando em nossa Demo Store).

npm run seeder:seed -ws --if-present

Se o comando acima for executado sem erros, pule para a etapa 4. Caso contrário, você ainda poderá propagar dados de amostra em sua organização usando a CLI executando o seguinte:

commercelayer seeder:seed -b custom -n demo_store_full -u ./demo-store-core/packages/setup/

4. Escolha os países onde você vai vender

O arquivo json/countries.json contém uma lista de países disponíveis para seu comércio eletrônico. Você pode alterá-lo com seu editor preferido. Apenas certifique-se de substituir todas as descobertas de "market": xxx pelos mercados relacionados da sua organização. Você pode obter a lista de seus mercados no painel de administração do Commerce Layer ou executando este comando:

npm run markets -ws --if-present

5. Veja em ação

npm run dev

# http://localhost:3000/ 

Gerenciando atualizações

Você sempre pode encontrar o código mais recente do demo-store-core em sua ramificação main .

Para atualizar sua Demo Store com as alterações mais recentes, você pode simplesmente executar:

git submodule update --remote
npm install

Às vezes pode acontecer que uma nova versão principal contenha alterações importantes. Nesse caso, ao atualizar para a versão mais recente, sua Demo Store poderá parar de funcionar e você precisará resolver manualmente todos os problemas seguindo as notas de lançamento.

Se desejar, você pode receber uma notificação do GitHub assim que uma nova versão for lançada.

Personalização

Ao usar nosso modelo Demo Store, você pode personalizar três elementos principais: dados de conteúdo, localidades e arquivos de configuração.

️ Melhoraremos continuamente nossa Demo Store para adicionar novos recursos e otimizar os existentes. Ao atualizar para a versão mais recente, a compilação poderá falhar. Dê uma olhada nas notas de versão para entender como consertar isso atualizando seus arquivos personalizados.

Arquivos de dados JSON

Conforme mencionado anteriormente, nossa Demo Store é construída em torno de um conjunto de dados armazenados como arquivos JSON, para dissociá-los de quaisquer serviços de terceiros. Para construir sua loja você terá que criar e gerenciar esses arquivos.

Os arquivos JSON estão localizados em data/json/ , mas você pode escolher uma posição diferente alterando a variável de ambiente NEXT_PUBLIC_JSON_DATA_FOLDER .

Os arquivos de definição de tipo estão localizados em packages/types/src/json/ . Estamos usando zod para validação de esquema. Dê uma olhada nesses arquivos para entender qual estrutura você deve seguir.

Quando terminar todas as alterações, você pode verificar se tudo está correto executando:

 npm run test:data

Arquivos de dados de localidade

Nossa Demo Store é um site multilíngue. Ao criar seus dados na etapa anterior, você provavelmente notou que alguns campos foram localizados. Você pode adicionar novos idiomas ou alterar traduções existentes.

Os arquivos JSON de localidade estão localizados em data/locales/ , mas você pode escolher uma posição diferente alterando a variável de ambiente NEXT_PUBLIC_LOCALES_DATA_FOLDER .

Faça o seguinte para começar a personalizar as localidades:

cp -r ./demo-store-core/packages/website/data/locales ./data/locales

 # .env.local
NEXT_PUBLIC_LOCALES_DATA_FOLDER =../../../data/locales/

Arquivos de configuração

Os arquivos de configuração estão localizados em config/ , mas você pode escolher uma posição diferente alterando a variável de ambiente NEXT_PUBLIC_CONFIG_FOLDER .

Existem três arquivos de configuração que você pode gerenciar:

• general.config.js
  Este arquivo contém a configuração geral.

• facets.config.js
  Este é o arquivo de configuração de facetas. Você pode escolher a ordem em que serão exibidos no painel de filtros, sua aparência e as regras de classificação de seus valores.
  

• variants.config.js
  Este é o arquivo de configuração de variantes. Você pode escolher a ordem em que serão exibidos na página de detalhes do produto e sua aparência.
  

Faça o seguinte para começar a personalizar a configuração:

cp -r ./demo-store-core/packages/website/config ./config

 # .env.local
NEXT_PUBLIC_CONFIG_FOLDER =../../../config/

Variáveis ​​de ambiente adicionais

Existem algumas variáveis ​​de ambiente que você pode usar para personalizar sua loja. Para obter uma lista e descrição completas, você pode dar uma olhada no arquivo adicional-env.d.ts.

Implantar

Você pode implantar a Demo Store onde preferir. Você só precisa:

1. Defina todas as variáveis ​​de ambiente no sistema que você usará para executar o build, de acordo com suas necessidades.
2. Decida se deseja usar a geração de sites estáticos ou a renderização no lado do servidor.

A Demo Store foi projetada para ser SSG em primeiro lugar, mas você pode mudar para SSR rapidamente. Testamos algumas maneiras de implantá-lo (por exemplo, usando GitHub Workflow, Netlify, Vercel, etc.) e você pode encontrar mais informações sobre isso aqui. Se você fez diferente ou usou outros serviços e deseja compartilhar as etapas com a comunidade, participe da discussão e desde já agradecemos!

Geração de site estático

Para construir e implantar a Demo Store:

1. Defina a seguinte variável de ambiente de acordo:

    NEXT_PUBLIC_DATA_FETCHING =ssg

2. Execute npm run build para criar uma compilação de produção estaticamente otimizada do seu aplicativo.

3. Copie a pasta demo-store-core/packages/website/out para sua hospedagem estática preferida.

Renderização do lado do servidor

A Demo Store pode ser implantada em qualquer provedor de hospedagem que suporte Node.js. Para fazer isso:

1. Defina a seguinte variável de ambiente de acordo:

    NEXT_PUBLIC_DATA_FETCHING =ssr

2. Execute npm run build para criar uma compilação de produção otimizada do seu aplicativo.

3. Execute npm start para iniciar o servidor Node.js no modo de produção.

Precisar de ajuda?

• Junte-se à comunidade Discord do Commerce Layer.
• Abra uma nova discussão de perguntas e respostas
• Envie-nos um ping no Bluesky, X (antigo Twitter) ou LinkedIn.
• Existe um bug? Crie um problema neste repositório.

Solução de problemas

1. P. Mesmo que eu tenha alterado NEXT_PUBLIC_JSON_DATA_FOLDER , NEXT_PUBLIC_LOCALE_DATA_FOLDER ou NEXT_PUBLIC_CONFIG_FOLDER , o site ainda se refere a arquivos anteriores.

   A. Essas variáveis ​​de ambiente são usadas como alias no Webpack. A partir do Webpack 5, foi introduzido o cache para compilações mais rápidas. Alterar essas variáveis ​​de ambiente não invalidará o cache do Webpack. Você deve remover a pasta .next manualmente ou executando:

    # update the path if needed
   rm -rf demo-store-core/packages/website/.next/

Licença

Este repositório é publicado sob a licença do MIT.