Criar seu primeiro pacote desbloqueado

Objetivos de aprendizagem

Após concluir esta unidade, você estará apto a:

• Conhecer os comandos CLI para o empacotamento.
  
• Descrever os casos de uso básicos do empacotamento.
  
• Empacotar o exemplo de aplicativo DreamHouse LWC e instalá-lo em um Trailhead Playground.
  

Nota

Deseja aprender em português (Brasil)? Comece o desafio em um Trailhead Playground de português (Brasil) e use as traduções fornecidas entre parênteses para navegar. Copie e cole somente os valores em inglês porque as validações dos desafios dependem de dados em inglês. Se você não passar no desafio em sua organização de português (Brasil), recomendamos que (1) mude o local para os Estados Unidos, (2) mude o idioma para inglês, seguindo as instruções aqui, e (3) clique novamente no botão “Validar o desafio”.

Consulte o emblema Trailhead no seu idioma para saber mais sobre como aproveitar a experiência de Trailhead em outros idiomas.

Por que adoramos o desenvolvimento com pacotes

Para nós, o empacotamento é um dos recursos para desenvolvedores da Salesforce Platform mais empolgantes. Fica lado a lado com outras revoluções famosas, como o pão fatiado, o celular e os serviços de streaming de vídeo. No entanto, caso você ainda não esteja convencido, vamos resumir as principais vantagens que descobrimos até hoje. O desenvolvimento com pacotes:

• Segue as melhores práticas referentes ao ciclo de vida do desenvolvimento de software. É compatível com os recursos do Salesforce DX: os projetos, os comandos CLI e as organizações temporárias foram criados pensando especificamente no empacotamento.
  
• Encapsula todas as alterações controladas entre os estágios do ciclo de vida em um artefato com versões.
  
• Torna mais fácil acomodar os futuros pedidos de novos recursos. Adiciona, atualiza e remove componentes de seu pacote de modo simples.
  
• Proporciona um histórico de auditoria melhorado, facilitando o controle e a compreensão das alterações feitas em sua organização de produção.
  
• Organiza a origem. Fica muito mais fácil saber qual componente pertence a cada aplicativo e recurso.
  
• Promove o desenvolvimento iterativo e modular.
  
• Aceita interdependências entre pacotes desbloqueados. Um único pacote desbloqueado pode depender de vários outros pacotes desbloqueados, e de pacotes gerenciados de primeira e segunda geração.
  
• Aceita a integração contínua e o envio contínuo porque os comandos de CLI para empacotamento permitem automatizar totalmente cada etapa no pipeline de implantação.
  

Casos de uso simples do empacotamento

Os pacotes desbloqueados são perfeitos para aplicativos empresariais internos. Por exemplo:

• O grupo de negócios financeiros quer que a equipe de TI crie um aplicativo para os funcionários enviarem suas despesas. Sua equipe decide desenvolver e enviar esse aplicativo usando os pacotes desbloqueados.
  
• A equipe de RH quer que a equipe de TI crie um aplicativo para os funcionários indicarem possíveis candidatos. Os funcionários usarão o aplicativo Recomendação para publicar vagas de emprego, indicar colegas e receber bônus por indicação. Sua equipe decide desenvolver e enviar esse aplicativo usando os pacotes desbloqueados.
  

Em cada um desses casos, você começa um projeto completamente novo e toda a origem fica contida no formato de origem de projeto do Salesforce DX (e comprometida com seu sistema de controle de versão). Quando estiver pronto para enviar um desses aplicativos, você cria um pacote desbloqueado que pode ser testado em uma organização temporária ou um sandbox e, depois, instalado em sua organização de produção. E quando a equipe precisa de um recurso novo, é possível adicioná-lo e criar uma nova versão do pacote. Simples. Moleza!

Agora que você já está a par das vantagens do desenvolvimento com pacotes, vamos mostrar como criar um pacote desbloqueado.

Configure o ambiente

Antes de irmos ao que interessa, vamos configurar um novo Trailhead Playground e habilitar o Dev Hub e o empacotamento nele.

Nota: Se você estiver acompanhando as etapas desta seção, precisará criar outro novo Trailhead Playground quando iniciar o desafio prático.

1. Para criar um novo Trailhead Playground, encontre o desafio prático no final desta unidade. Clique nas informações do Playground à esquerda do botão Launch (Iniciar).
   
   
2. Em seguida, selecione Create Playground (Criar Playground).
   
   Nota: Mesmo que seja possível reutilizar um Trailhead Playground existente, começar com um playground novo é uma garantia de que você está trabalhando com um ambiente limpo.
   
3. Depois de criar um novo Trailhead Playground, clique em Launch (Iniciar) para abrir o playground. Em seguida, certifique-se de saber o nome de usuário e a senha do playground. Essas informações serão necessárias em próximas etapas.
   Consulte Obter seu nome de usuário e redefinir a sua senha.
   
4. Em Configuração no Trailhead Playground, digite Dev Hub na caixa Busca rápida e selecione Dev Hub. Clique em Ativar Dev Hub e, em seguida, clique em Ativar pacotes desbloqueados e pacotes de segunda geração gerenciados.
   
5. Crie uma conta GitHub, se ainda não tiver uma.
   
6. Instale o Salesforce CLI no seu computador.
   

Copie o código fonte do DreamHouse

Para fins de demonstração, vamos fingir que você está criando e apresentando o aplicativo DreamHouse LWC para uma das equipes da sua empresa.

Se você usa atualmente os recursos e ferramentas do Salesforce DX, talvez já esteja à vontade com o exemplo de repositório DreamHouse LWC. O DreamHouse LWC é um aplicativo independente que incorpora muitos dos recursos disponíveis na Salesforce Platform. Ele usa componentes Web do Lightning, Apex e muito mais. Nele, os usuários podem procurar imóveis e falar com corretores on-line.

Para que você possa se concentrar no empacotamento, vamos extrair o código fonte do DreamHouse LWC e os respectivos arquivos de projeto do Salesforce DX, que já foram criados. Embora este exemplo use apenas um pacote, um projeto do Salesforce DX pode conter vários. Você pode isolar pacotes diferentes com base na estrutura de diretório e compartilhar componentes quando for o caso.

Criando um pacote para esse aplicativo, fica fácil instalá-lo em organizações temporárias, UAT, sandboxes e organizações de produção conforme você itera pelo ciclo de vida do desenvolvimento.

Vamos acompanhá-lo durante todo o processo usando as ferramentas especialmente criadas para o desenvolvimento com pacotes.

Vamos copiar o código fonte do aplicativo DreamHouse Lightning Web Components (LWC).

Em uma janela de comando, mude para o diretório onde você quer colocar o código-fonte. Depois, execute o comando.

git clone https://github.com/trailheadapps/dreamhouse-lwc.git

O comando git clone cria a pasta dreamhouse-lwc usando a estrutura do projeto do Salesforce DX, que contém um arquivo de projeto do DX e um arquivo de definição de organização temporária. Não se assuste se a sua versão do projeto for um pouco diferente, pois o repositório DreamHouse LWC é atualizado com frequência.

Configurar seu pacote

1. Your Trailhead Playground is also your Dev Hub org. To create a package, we need to first authorize to your Dev Hub org, and log in to it.
   

   sf org login web --set-default-dev-hub --alias DevHub

2. In the command window, let’s double check that the Dev Hub org is connected.
   sf org listThe output of this command lists any org that you’re connected to, including Dev Hub, Trailhead Playgrounds, and scratch orgs. The (D) indicates your default Dev Hub org. 
   

   === Orgs
        ALIAS       USERNAME                             ORG ID              CONNECTED STATUS
   ───  ──────────  ───────────────────────────────      ──────────────────  ────────────────
   (D)  DevHub      myDevHub@example.com                 00DB0000000Ige5MAC  Connected
        MyTP        myName@mindful-raccoon-8184t4.com    00D6A000000fH8CUAU  Connected
        TestingOrg  name@example.com                     00D4x000006sFonEAE  Connected
   ALIAS            USERNAME                             ORG ID              EXPIRATION  DATE
   ────────         ───────────────────                  ──────────────────  ────────────────
   Scratch1         test@example.com                     00DZ000000N8ItoMAF  2021-02-24

3. Mude para o diretório dreamhouse-lwc em seu computador.
   
4. Abra o sfdx-project.json em seu editor de texto favorito e anote o número da sourceApiVersion.
   
5. DreamHouse LWC is an open-source project with many contributors. To ensure that you can successfully complete the challenge, replace the contents of the sfdx-project.json file with the following code.
   

   {
      "packageDirectories": [
         {
            "path": "force-app",
            "default": true
         }
      ],
      "namespace": "",
      "sfdcLoginUrl": "https://login.salesforce.com",
      "sourceApiVersion": "61.0"
   }

6. Certifique-se de que o número da sourceApiVersion no trecho de código corresponde ao número da versão que você anotou do arquivo original. Se não, então atualize o número da sourceApiVersion.
   

Por que não usamos namespace neste exemplo?

Embora o namespace seja opcional nos pacotes desbloqueados, incluí-lo ajuda a manter os componentes do pacote organizados. No entanto, como os namespaces exigem mais configuração e antecipação, vamos deixá-los de lado nesta unidade.

Caso esteja migrando metadados da sua sopa da felicidade para o pacote desbloqueado, crie os pacotes desbloqueados sem namespace. Assim, quando os metadados saírem do estado sem pacote para entrar no pacote desbloqueado, o nome da API dos elementos de metadados permanecerá o mesmo.

Criar o pacote

Quando você clonou o aplicativo DreamHouse LWC do GitHub, colocou todos os arquivos de dados no diretório do seu projeto. Agora você pode criar o pacote de base sem mais delongas.

Esta seção apresenta o fluxo de trabalho para criar um pacote usando o exemplo de repositório DreamHouse LWC.

1. Num terminal ou prompt de comando, mude para o diretório dreamhouse-lwc.
   
2. Create an unlocked package without a namespace, and supply the alias or username for your Dev Hub org if it’s not already set as the default:
   

   sf package create --name dreamhouse --description "My Package" --package-type Unlocked --path force-app --no-namespace --target-dev-hub DevHub

• --name é o nome do pacote. Esse nome é um alias que você pode usar ao executar comandos para empacotamento subsequentes.
  
• --path é o diretório que apresenta o conteúdo do pacote.
  
• --packagetype indica que tipo de pacote você está criando; neste caso, desbloqueado.
  

3. Open sfdx-project.json. Boom! In packageDirectories, you can see the package name that you defined, with placeholders for the version name and version number. The command also creates a packageAliases section, which maps the package name (alias) to its corresponding package ID (0Ho).
   

   {
      "packageDirectories": [
         {
            "path": "force-app",
            "default": true,
            "package": "dreamhouse",
            "versionName": "ver 0.1",
            "versionNumber": "0.1.0.NEXT"
         }
      ],
      "namespace": "",
      "sfdcLoginUrl": "https://login.salesforce.com",
      "sourceApiVersion": "61.0",
      "packageAliases": {
         "dreamhouse": "0Hoxxx"
      }
   }

Se você não lembrar do alias do pacote ou do ID de pacote, liste todos os pacotes associados ao seu Dev Hub executando sf package list.

Criar uma organização temporária para testar sua versão do pacote

Vamos criar uma organização temporária na qual instalaremos o pacote desbloqueado com o alias MyScratchOrg. O teste em uma organização temporária é uma forma prática de realizar a fase de teste da unidade no ciclo de vida do desenvolvimento por empacotamento.

sf org create scratch --definition-file config/project-scratch-def.json --duration-days 30 --alias MyScratchOrg --target-dev-hub DevHub

Esse comando usa o arquivo de definição da organização temporária padrão e cria uma organização temporária da Developer Edition da mesma edição de seu Trailhead Playground. Repare que a duração é definida como 30 dias, dando muito tempo para que você termine o trabalho dentro de um sprint de desenvolvimento (ou conclua este módulo do Trailhead).

Criar a versão do pacote e instalá-la na organização temporária

Quando estiver pronto para liberar o pacote, crie um instantâneo dele, chamado de “versão do pacote”. A instalação da versão do pacote se assemelha à implantação de metadados. Lembre-se: depois de criada, a versão do pacote serve como artefato imutável que contém um conjunto específico de metadados.

1. Abra sfdx-project.json com o editor de texto desejado para atualizar as opções da versão do pacote.
   
2. Change the versionName to Version 1.0, and the versionNumber to 1.0.0.NEXT. The force-app directory is the default (and only) package directory, so any source included in it becomes part of the package. Once updated, the sfdx-project.json file looks like this:
   

   {
      "packageDirectories": [
         {
            "path": "force-app",
            "default": true,
            "package": "dreamhouse",
            "versionName": "Version 1.0",
            "versionNumber": "1.0.0.NEXT"
         }
      ],
      "namespace": "",
      "sfdcLoginUrl": "https://login.salesforce.com",
      "sourceApiVersion": "61.0",
      "packageAliases": {
         "dreamhouse": "0Hoxxx"
      }
   }

3. Salve o arquivo sfdx-project.json.
   
4. In the dreamhouse-lwc directory, create the package version, which associates the metadata with the package.
   The Apex code in unlocked packages must meet a minimum 75% code coverage requirement, before the package can be installed in a production org. We didn’t calculate code coverage in this example, because we know this sample Dreamhouse LWC repo doesn’t have enough Apex test coverage.
   

   sf package version create --package dreamhouse --installation-key test1234 --wait 10 --target-dev-hub DevHub

• -p é o alias do pacote que mapeia para o ID de pacote.
  
• -d é o diretório que apresenta o conteúdo do pacote.
  
• -k é a chave de instalação que impede que seu pacote seja instalado por pessoas não autorizadas.
  

5. It’s normal for the package version creation process to take several minutes. You see status messages that tell you what’s going on. When the package version creation is complete, you see this message.
   

   Successfully created the package version [08cxxx]. Subscriber Package Version Id: 04txxx.
   Package Installation URL: https://login.salesforce.com/packaging/installPackage.apexp?p0=04txxx
   As an alternative, you can use the "sf package install" command.

6. Notice that the packageAliases section in sfdx-project.json has a new entry.
   

   "packageAliases": {
      "dreamhouse": "0Hoxxx",
      "dreamhouse@1.0.0-1": "04txxx"
   }

7. Use the package version alias to install the package version in the scratch org that you created earlier.
   

   sf package install --wait 10 --publish-wait 10 --package dreamhouse@1.0.0-1 --installation-key test1234 --no-prompt --target-org MyScratchOrg 

   It can take several minutes for a newly created package version to be available in the scratch org. The installation begins once the package version is available. When the package install is complete, you see this message. Successfully installed package [04t3XXX]
8. After the package is installed, open the scratch org to view the package.
   

   sf org open --target-org MyScratchOrg

9. Em Configuração, digite Pacotes instalados na caixa Busca rápida e selecione Pacotes instalados.
   

Como se trata de um pacote desbloqueado, você pode fazer alterações diretamente na organização temporária, extrair os metadados atualizados e, depois, criar a nova versão do pacote. Por enquanto, o aplicativo DreamHouse LWC já tem tudo o que é necessário, ou seja, podemos prosseguir e liberar o pacote.

Liberar a versão do pacote

Ainda não discutimos um recurso, o status do pacote. Quando os pacotes são criados, eles têm o status beta. Não é possível instalar pacotes beta em uma organização de produção. Trata-se de uma proteção para garantir que a versão do pacote lançada esteja pronta para a produção. Quando você souber que a versão está pronta para ganhar o mundo, basta promover o lançamento.

O exemplo de repositório Dreamhouse LWC que estamos usando nesta unidade evolui e pode nem sempre ter testes do Apex suficientes para atender ao requisito de 75% de  cobertura de código. Portanto, vamos pular a promoção e continuar usando a versão beta do pacote que você criou.

É assim que fica o comando de promoção de versão do pacote, mas se você tentar esse comando agora, receberá uma mensagem de erro.

sf package version promote --package dreamhouse@1.0.0-1 --target-dev-hub DevHub

Instalar a versão do pacote na organização

Por último, mas não menos importante, instale a versão do pacote na organização. Lembre-se: é possível instalar versões do pacote em organizações temporárias, sandboxes e Trailhead Playgrounds (organizações DE). Você pode instalar uma versão do pacote liberada em qualquer organização. Normalmente, neste estágio, você instalará a versão do pacote em uma sandbox, mas, para este exercício, iremos instalar o pacote no seu Trailhead Playground.

1. To install the package version in to your Trailhead playground, you must first add it to your list of authorized orgs.
   you must first add it to your list of authorized orgs.
   

   sf org login web --alias MyTP

   We suggest creating an alias for the Trailhead Playground, in this example, MyTP. Once you log in to an org, the CLI remembers your credentials. All you need to do is remember the org’s alias when issuing subsequent commands. If you don’t know the username and password for your Trailhead Playground, see Getting Your Username and Resetting Your Password.
   
2. Install the package version in the Trailhead playground.
   

   sf package install --wait 10 --publish-wait 10 --package dreamhouse@1.0.0-1 --installation-key test1234 --no-prompt --target-org MyTP

3. Open your Trailhead playground.
   

   sf org open --target-org MyTP

4. No Trailhead Playground, em Configuração, digite Pacotes instalados na caixa Busca rápida e selecione Pacotes instalados. Você também receberá um email que confirma a instalação bem-sucedida do pacote desbloqueado.
   
5. Clique em dreamhouse e em Exibir componentes.
   
6. No Iniciador de aplicativos, encontre e selecione o aplicativo DreamHouse e confira alguns de seus recursos.
   

Recursos

• Guia de configuração da CLI do Salesforce
• Repositório DreamHouse LWC
• Salesforce DX Trailblazer Community