Arquivos de configuração

Com os arquivos de configuração, é possível personalizar vários aspectos do funcionamento de seu PWA Kit, inclusive: acesso à API, formatação de URL, tratamento de vários sites, proxy de solicitações e renderização no lado do servidor.

Um arquivo de configuração pode ser criado em JavaScript, YAML ou JSON. Estas extensões de arquivo são compatíveis: .js, .yml, .yaml e .json.

Quando um projeto do PWA Kit é criado com o modelo do Retail React App, há apenas um arquivo de configuração: app/config/default.js. Os objetos de configuração exportados são definidos com base nas opções fornecidas ao pwa-kit-create-app, mas você pode atualizar essa configuração quando quiser. Em geral, são necessárias atualizações após a geração do projeto para manter a sincronização com as alterações às instâncias do B2C Commerce.

Para ser compatível com renderização isomórfica, os valores da configuração são serializados na página. Não inclua segredos na configuração!

É possível substituir o arquivo default.js ou complementá-lo com arquivos de configuração adicionais, pois o PWA Kit é compatível com configurações específicas do ambiente, abordadas mais adiante neste guia.

Vamos começar tratando de propriedades e objetos de configuração específicos que estão disponíveis no default.js e em qualquer outro arquivo de configuração.

A string do projeto que associa seu aplicativo ao Managed Runtime não é parte do arquivo de configuração, mas pode ser encontrada na propriedade name, localizada na parte superior do arquivo package.json, na raiz do seu diretório do projeto. Após a geração do projeto, é possível mudar o valor de name para corresponder ao ID do projeto exibido no Runtime Admin.

Antes da versão 1.5.0 do PWA Kit, essas configurações estavam em app/api.config.js.

Para configurar o acesso à B2C Commerce API e Open Commerce API (OCAPI), edite o objeto app.commerceAPI exportado do arquivo de configuração.

Confira a seguir um trecho de código anotado com exemplos de valores:

Para configurar o acesso à Einstein API, edite o objeto app.einsteinAPI.

Veja outro trecho de código anotado com exemplos de valores:

Para obter mais informações sobre a classe CommerceAPI que usa o objeto de configuração no snippet de código anterior, consulte nosso guia de arquitetura para o Retail React App.

Para obter mais informações sobre as tarefas de configuração no Account Manager e no Business Manager e habilitar o acesso à API para uma instância do B2C Commerce, consulte nosso guia Como configurar o acesso à API

É possível personalizar como os URLs da loja virtual são formatados no objeto app.url.

Por padrão, o objeto app.url é configurado com os seguintes valores:

Com essas configurações-padrão, o site e a localidade atuais são mostrados no caminho do URL.

Escolha como e se a localidade atual é exibida no URL ao definir um dos valores a seguir em url.locale:

  • path: A localidade é incluída no caminho do URL. Exemplo: /en-US/women/dress
  • query_param: a localidade é incluída como um parâmetro de consulta. Exemplo: /women/dress?locale=en-US
  • none: a localidade não é incluída no URL. Exemplo: /women/dress

url.showDefaults: este valor booleano define se os valores-padrão do site ou da localidade são exibidos no URL. O padrão é “false”.

Os sites configurados para seu aplicativo são extraídos para um arquivo denominadoconfig/sites.js. Ele é importado para cada arquivo de configuração e exportado no objeto app. Os arquivos são separados dessa maneira para que você consiga sincronizar com mais facilidade os sites compatíveis com seu aplicativo e os sites definidos no back-end do Business Manager. Se você preferir, é possível definir os sites diretamente no arquivo de configuração.

O objeto app também contém outras configurações para o gerenciamento de vários sites e seus aliases. Confira mais detalhes sobre essas configurações em nosso guia sobre Vários sites.

Esta funcionalidade é configurada na matriz ssrParameters.proxyConfigs, abordada em detalhes no guia sobre Proxy de solicitações.

Antes da versão 1.5.0 do PWA Kit, essas configurações estavam em package.json.

A tabela a seguir destaca as opções de configuração relacionadas à renderização no lado do servidor. Essas opções não fazem parte do objeto app e são expressas como propriedades individuais do objeto principal exports.

Propriedade Descrição
ssrParameters.ssrFunctionNodeVersion String que determina a versão do nó a ser usada para executar o App Server.

Valores permitidos: 16.x.
ssrEnabled Valor booleano que habilita ou desabilita a criação dos arquivos necessários para a renderização no lado do servidor. Definir este valor como false foi descontinuado desde agosto de 2021.
ssrOnly Matriz de expressões glob na qual* é um curinga que corresponde a zero ou mais instâncias de qualquer caractere.

Determina quais arquivos estão exclusivamente disponíveis para o sistema de renderização do lado do servidor e que não estão disponíveis pelo caminho /mobify/bundle/.

Estes são os padrões para um projeto que acabou de ser gerado: ['ssr.js', 'ssr.js.map', 'node_modules/**/*.*']
ssrShared Matriz de expressões glob na qual* é um curinga que corresponde a zero ou mais instâncias de qualquer caractere.

Determina quais arquivos estão disponíveis para o sistema de renderização no lado do servidor bem como pelo caminho /mobify/bundle/.

O padrão é o projeto criado mais recentemente:

É possível incluir várias configurações no diretório app/config/, inclusive arquivos de configuração para ambientes específicos.

As configurações específicas do ambiente tornam suas implementações mais eficientes e flexíveis. Por exemplo, você pode:

  • implantar um só pacote em vários ambientes do Managed Runtime, com cada ambiente conectado a uma instância diferente do B2C Commerce;
  • conectar sua própria sandbox sob demanda durante o desenvolvimento local, mas conectá-la a diferentes instâncias quando for feita a implantação no Managed Runtime.

Para criar um arquivo de configuração específico do ambiente, siga as mesmas convenções aplicadas em default.js, mas use o nome do ambiente de destino como nome-base do arquivo. Lembre-se de usar um dos arquivos compatíveis e a extensão correspondente. Exemplos: production.js, staging.json.

Um aplicativo do PWA Kit determina a configuração correta a ser carregada realizando uma busca em app/config e fazendo estas perguntas na ordem especificada:

  1. Há um arquivo com o mesmo nome do ambiente em execução no Managed Runtime?
  2. Se a execução é local, há um arquivo chamado local com uma extensão compatível?
  3. Se nenhum arquivo de configuração foi localizado, há um arquivo chamado default com uma extensão compatível?

Quando a resposta a uma dessas perguntas é “Sim”, o PWA Kit interrompe a busca e carrega o arquivo em questão.

Se dois arquivos têm o mesmo nome-base, mas apresentam extensões diferentes, a extensão com prioridade mais alta é escolhida. As extensões de arquivo compatíveis apresentam a seguinte ordem de prioridade, da mais alta à mais baixa: .js, .yml, .yaml ou .json. Isso significa que entre default.js e default.json, o PWA Kit carregaria default.js porque ela tem prioridade mais alta.