Visão geral do Front-end - Parte 1 - Internet Computer

A Internet Computer permite que você hospede front-ends Web 3.0 para seus dapps, usando nosso agente JavaScript. Ao usar o cânister de ativos fornecido pelo dfx para fazer upload de arquivos estáticos para a IC, você poderá executar todo o seu aplicativo em tecnologia descentralizada. Esta seção examina mais de perto o modelo de front-end padrão fornecido pelo comando dfx new, opções de configuração de front-end e o uso de outros frameworks para criar a interface do usuário para seus projetos.

Aqui estão alguns links rápidos para tutoriais com códigos de exemplo para vários estágios de desenvolvimento de seu dapp de front-end:

• Um tutorial sobre como construir um dapp em React - Personalizar o front-end
• Usando o Candid como uma interface básica para expor e testar as funções em um cânister.
• Usando HTML bruto e JavaScript para exibir uma página de entrada HTML simples.
• Usando React e JavaScript compilado para incorporar atributos e elementos HTML diretamente em uma página.
• Usando React e TypeScript para importar propriedades CSS de um arquivo externo.

Como os modelos padrão são usados

Como você deve ter notado nos tutoriais, os projetos incluem os arquivos de modelo index.js e webpack.config.js.

Por padrão, o arquivo index.js importa um agente que está localizado na pasta src/declarations. Esse diretório será gerado pelo dfx quando você executar o dfx deploy, localmente ou ao implantar na IC.

Esse código gerado ficará assim:

import { Actor, HttpAgent } from "@dfinity/agent";

// Importa a interface do candid 
import { idlFactory } from './hello.did.js';
// CANISTER_ID é substituído pelo webpack baseado no ambiente do node
export const canisterId = process.env.HELLO_CANISTER_ID;

/**
*
* @param {string | Principal} canisterId Canister ID of Agent
* @param {{agentOptions?: import("@dfinity/agent").HttpAgentOptions; actorOptions?: import("@dfinity/agent").ActorConfig}} [options]
* @return {import("@dfinity/agent").ActorSubclass<import("./hello.did.js")._SERVICE>}
*/
export const createActor = (canisterId, options) => {
 const agent = new HttpAgent({ ...options?.agentOptions });

 // Buscar a chave raiz para validação do certificado durante o desenvolvimento
 if(process.env.NODE_ENV !== "production") agent.fetchRootKey();

 // Cria um ator usando a interface do candid e o HttpAgent
 return Actor.createActor(idlFactory, {
   agent,
   canisterId,
   ...options?.actorOptions,
 });
};

/**
* Um agente pronto para uso para o cânister hello
* @type {import("@dfinity/agent").ActorSubclass<import("./hello.did.js")._SERVICE>}
*/
export const hello = createActor(canisterId);

Então, se você retornar ao index.js, poderá ver que ele pega o ator gerado e o usa para fazer uma chamada para o método greet do cânister hello:

import { hello } from "../../declarations/hello";

document.getElementById("clickMeBtn").addEventListener("click", async () => {
 const name = document.getElementById("name").value.toString();
 // Interaja com o ator hello, chamando o método greet
 const greeting = await hello.greet(name);

 document.getElementById("greeting").innerText = greeting;
});

Em muitos projetos, você poderá usar o código em declarations sem nenhuma alteração e fazer suas alterações em hello_assets/src. No entanto, se o seu projeto tiver requisitos adicionais, continue lendo abaixo.

Modificando a configuração do webpack

Como o webpack é um empacotador de módulos popular e altamente configurável para aplicativos baseados em JavaScript, novos projetos criam um arquivo webpack.config.js padrão que facilita a adição de módulos específicos—como react e markdown—que você deseja usar.

Se você revisar o código no arquivo de modelo webpack.config.js, verá que ele infere IDs de cânister de seu .dfx/local/canister_ids.json para desenvolvimento local e de './canister_ids.json' para quaisquer outros ambientes que você configurar. Ele decide qual rede usar com base em uma variável de processo DFX_NETWORK, ou se NODE_ENV está definido como "production".

Você pode ver essas etapas no seguinte bloco de código:

let localCanisters, prodCanisters, canisters;

try {
 localCanisters = require(path.resolve(".dfx", "local", "canister_ids.json"));
} catch (error) {
 console.log("Nenhum canister_ids.json local encontrado. Continuando a implantação");
}

function initCanisterIds() {
 try {
   prodCanisters = require(path.resolve("canister_ids.json"));
 } catch (error) {
   console.log("Nenhuma canister_ids.json de implantação encontrado. Continuando com os locais");
 }

 const network =
   process.env.DFX_NETWORK ||
   (process.env.NODE_ENV === "production" ? "ic" : "local");

 canisters = network === "local" ? localCanisters : prodCanisters;

 for (const canister in canisters) {
   process.env[canister.toUpperCase() + "_CANISTER_ID"] =
     canisters[canister][network];
 }
}
initCanisterIds();

Configuração de input e output

Em muitos casos, você pode usar o arquivo webpack.config.js padrão como está, sem nenhuma modificação, ou pode adicionar plugins, módulos e outras configurações personalizadas para atender às suas necessidades. As alterações específicas que você faz na configuração do webpack.config.js dependem em grande parte das outras ferramentas e frameworks que você deseja usar.

Por exemplo, se você testou os tutoriais “Personalizar o front-end” ou “Adicionar uma folha de estilo”, você pode ter modificado a seção a seguir para trabalhar com React JavaScript:

module: {
     rules: [
       { test: /\.(ts|tsx|jsx)$/, loader: "ts-loader" },
       { test: /\.css$/, use: ['style-loader','css-loader'] }
     ]
   }
 };
}

Se seu aplicativo não usa o dfx para executar seu script de compilação, você mesmo pode fornecer as variáveis. Por exemplo:

DFX_NETWORK=staging NODE_ENV=production HELLO_CANISTER_ID=rrkah... npm run build

Garantindo que o node esteja disponível em um projeto

Como os projetos dependem do webpack para fornecer o framework para o front-end padrão, você deve ter o node.js instalado em seu ambiente de desenvolvimento e acessível no diretório do projeto.

• Se você quiser desenvolver seu projeto sem usar a configuração padrão do webpack e os aliases do cânister, poderá remover o cânister assets do arquivo dfx.json ou construir seu projeto usando um nome de cânister específico. Por exemplo, você pode optar por compilar apenas o programa hello sem recursos de front-end executando o seguinte comando:
  

  dfx build hello
  

• Se você estiver usando a configuração padrão do webpack e a execução do dfx build falhar, tente executar o npm install no diretório do projeto e, em seguida, execute novamente o dfx build.

• Se executar o npm install no diretório do projeto não corrigir o problema, você deve verificar a configuração do arquivo webpack.config.js quanto a erros de sintaxe.

Usando outros módulos com o framework React

Vários tutoriais e projetos de amostra no repositório de exemplos ilustram como adicionar módulos React usando o comando npm install. Você pode usar esses módulos para construir os componentes da interface do usuário que deseja usar em seu projeto. Por exemplo, você pode executar o seguinte comando para instalar o módulo react-router:

npm install --save react react-router-dom

Você pode então usar o módulo para construir um componente de navegação semelhante ao seguinte:

import React from 'react';
import { NavLink } from 'react-router-dom';

const Navigation = () => {
 return (
   <nav className="main-nav">
     <ul>
       <li><NavLink to="/myphotos">Lembre-se</NavLink></li>
       <li><NavLink to="/myvids">Assista</NavLink></li>
       <li><NavLink to="/audio">Ouça</NavLink></li>
       <li><NavLink to="/articles">Leia</NavLink></li>
       <li><NavLink to="/contribute">Escreva</NavLink></li>
     </ul>
   </nav>
 );
}

export default Navigation;

Iterar mais rápido usando webpack-dev-server

Começando com o dfx 0.7.7, agora fornecemos o webpack dev-server em nosso comando inicial dfx new.

O servidor de desenvolvimento do webpack—webpack-dev-server—fornece acesso na memória aos ativos do webpack, permitindo que você faça alterações e veja-as refletidas no navegador imediatamente usando o recarregamento ao vivo.

Para aproveitar o webpack-dev-server:

1. Crie um novo projeto e mude para o diretório do projeto.
2. Inicie a IC localmente se necessário, e implante como faria normalmente, por exemplo, executando o comando dfx deploy.

3. Inicie o servidor de desenvolvimento do webpack executando o seguinte comando:
   

   npm start
   

4. Abra um navegador da web e navegue até o cânister de ativos do seu aplicativo usando a porta 8080.

   Por exemplo:
   

   http://localhost:8080
   

5. Abra uma nova janela ou guia do terminal e navegue até o diretório do seu projeto.

6. Abra o arquivo index.js do seu projeto em um editor de textos e faça alterações no conteúdo.

   Por exemplo, você pode adicionar um elemento à página usando JavaScript:

   document.body.onload = addElement;
   

document.body.onload = addElement;

function addElement () {
  // crie um novo elemento div
  const newDiv = document.createElement("div");

  // e dê a ele algum conteúdo
  const newContent = document.createTextNode("Test live page reloading!");

  // adicione o nó de texto ao div recém-criado
  newDiv.appendChild(newContent);

  // adicione o elemento recém-criado e seu conteúdo no DOM
  const currentDiv = document.getElementById("div1");
  document.body.insertBefore(newDiv, currentDiv);
}

1. Salve suas alterações no arquivo index.js, mas deixe o editor aberto para continuar fazendo alterações.

2. Atualize o navegador ou espere que ele seja atualizado por conta própria para ver sua alteração.

   Quando terminar de trabalhar no front-end do seu projeto, você pode parar o servidor de desenvolvimento do webpack pressionando Control-C.

Usando outros frameworks

Você pode querer usar um empacotador diferente do webpack. As instruções para outros empacotadores ainda não estão prontas, mas se você estiver familiarizado com o seu, as etapas a seguir devem ajudá-lo:

1. Remova os scripts copy:types, prestart e prebuild do package.json
2. Execute dfx deploy para gerar as ligações locais para seus cânisteres
3. Copie as ligações geradas para um diretório onde você gostaria de mantê-las
4. Modifique declarations/<canister_name>/index.js e substitua process.env.<CANISTER_NAME>_CANISTER_ID pelo padrão equivalente para as variáveis de ambiente de seu empacotador
5. Alternativamente, codifique rigidamente o ID do cânister se esse for seu fluxo de trabalho preferido
6. Faça o commit das declarações e importe-as em seu repositório

Este guia foi publicado nos Docs do Desenvolvedor da Internet Computer. Tradução por Paulinho Giovannini.