title: Dfinity Frontend Development Tutorial#
date: 2021-08-05 15:58:32
Dfinity Frontend Development Tutorial#
> Author: ddd009 Please indicate the source when reprinting
Recently, Uniswap's frontend restrictions on certain cryptocurrencies have caused significant controversy. Dfinity is a great full-stack decentralized solution. This tutorial starts with dfx new helloworld and provides a detailed introduction on how to perform frontend development on Dfinity, as well as how to use the identity service provided by the official (identity.ic0.app). Let's join the world of decentralized frontend development together!
Before reading this article, you should be familiar with the use of the dfx development tool.
Tutorial Directory:#
* Starting with Hello World
* Frontend Scaffolding
* About Webpack Configuration and Dev Server
* How to Call Third-Party Canisters
* How to Use Internet Identity Service
Starting with Hello World#
In any directory, type dfx new helloworld, and you will get an initial project. Run dfx start & dfx deploy.
In the browser, enter frontendid.localhost:8000 (recommended) or localhost:8000/?canisterId=frontendid to get an interface similar to the one below.
The js code is as follows:
import { Actor, HttpAgent } from "@dfinity/agent";
import {
idlFactory as helloworld_idl,
canisterId as helloworld_id,
} from "dfx-generated/helloworld";
const agent = new HttpAgent();
const helloworld = Actor.createActor(helloworld_idl, {
agent,
canisterId: helloworld_id,
});
document.getElementById("clickMeBtn").addEventListener("click", async () => {
const name = document.getElementById("name").value.toString();
const greeting = await helloworld.greet(name);
document.getElementById("greeting").innerText = greeting;
});
This code first creates an HttpAgent for sending network requests. The default host for the agent is the address of your network environment. For example, if you deployed the frontend on localhost:8000, the agent will send requests to localhost:8000. Therefore, when using the dev server, you must pay attention to manually set the host. The following will explain the use of the dev server.
The following is the code to set the host (do not use in production)
const agent = new HttpAgent({
host: "http://localhost:8000",
})
Since the canisters in Dfinity use the Actor model, the frontend needs to create an actor before calling the canister. Here, you can simply understand it as a tool for calling the backend.
Next is the code for creating the actor, which requires three parameters: IDL, agent, and canisterId. The agent is the HttpAgent we just created, and the other two parameters will be introduced in How to Call Third-Party Canisters.
Once we complete the actor creation, we can call the backend's public methods through the actor. Note that these calls are all asynchronous. This tutorial will not elaborate on handling asynchronous calls; a recommended method is to use the async/await syntax. This code calls the greeting method and returns a piece of text.
This is the simplest Dfinity frontend application. Understanding these processes allows for interaction between the frontend and backend.
Frontend Scaffolding#
When we use frameworks like Vue, React, etc., for frontend development, we generally use scaffolding. There are many scaffolding options available in the Dfinity community, but most are currently in early stages and may encounter some issues.
create-ic-app
create-ic-app uses the new frontend build tool Vite, supporting React, Vue, TypeScript, Vanilla, etc., and is continuously updated. Vite's dev server is much faster than Webpack, so it is recommended to try it.
dfinity-vue
Vue scaffolding, integrated with Vuetify on one branch. If you need to use it, switch to the Vuetify branch.
cra-template-dfx
React scaffolding, last updated seven months ago, for reference only and not recommended for use.
About Webpack Configuration and Dev Server#
Dfinity projects use Webpack for packaging by default and automatically generate configuration files. What we need to do is actually very little.
Before discussing Webpack, we need to open dfx.json to understand the default configuration. If you frequently use the dfx tool, you should be familiar with dfx.json, but here is a brief explanation.
{
"canisters": {
...
//assets is the name of the frontend canister; in Dfinity, all code is deployed in canisters
"assets": {
//dependencies of the frontend canister
"dependencies": [
"backend"
],
//frontend.entrypoint is the entry point of the frontend file, which we will use in Webpack
"frontend": {
"entrypoint": "dist/index.html"
},
//source specifies the dist and src directories
"source": [
"dist/"
],
//specifies the canister type as a frontend canister
"type": "assets"
}
}
}
If you have used dfx, you will know that its development experience is very poor; every time you change the code, you have to recompile and deploy. For frontend development, we definitely need a dev server.
Install webpack-dev-server by simply typing npm i webpack-dev-server.
Once installed, you can start the Dev Server using the webpack serve or webpack-dev-server command. My version is 3.11.2, and you need to use webpack serve to start.
You can also configure the dev option in package.json.
This way, you can type npm run dev to start the Dev server.
Add the plugin in Webpack new webpack.HotModuleReplacementPlugin(),
Then add the dev server configuration.
devServer: {
hot: true,
}
This will enable automatic recompilation after modifying files.
How to Call Third-Party Canisters#
Content reference Kyle's Blog
Calling a canister requires two parameters: an IDL interface description and a canister ID.
IDL is a description of the canister's data types and interfaces. When deploying a canister locally, a canister.did.js file will be automatically generated.
export default ({ IDL }) => {
return IDL.Service({ 'greet' : IDL.Func([IDL.Text], [IDL.Text], []) });
};
export const init = ({ IDL }) => { return []; };
The IDL for Hello World looks like this:
import { idlFactory } from "dfx-generated/helloworld";
or
import { idlFactory } from './helloworld.did.js';
Importing IDL
If it is a third-party canister, you can find the corresponding IDL file at ic.rocks. For the identity service, for example:
Select JavaScript, create a new identity.did.js, and copy and paste it in (ts is identity.did.d.ts).
// src/declarations/identity/index.js
import { Actor, HttpAgent } from "@dfinity/agent";
// Imports and re-exports candid interface
import { idlFactory } from './identity.did.js';
export { idlFactory } from './identity.did.js';
// CANISTER_ID is replaced by webpack based on node environment
export const canisterId = process.env.IDENTITY_CANISTER_ID;
/**
*
* @param {string | import("@dfinity/principal").Principal} canisterId Canister ID of Agent
* @param {{agentOptions?: import("@dfinity/agent").HttpAgentOptions; actorOptions?: import("@dfinity/agent").ActorConfig}} [options]
* @return {import("@dfinity/agent").ActorSubclass<import("./identity.did.js")._SERVICE>}
*/
export const createActor = (canisterId, options) => {
const agent = new HttpAgent({ ...options?.agentOptions });
// Fetch root key for certificate validation during development
if(process.env.NODE_ENV !== "production") {
agent.fetchRootKey().catch(err=>{
console.warn("Unable to fetch root key. Check to ensure that your local replica is running");
console.error(err);
});
}
// Creates an actor using the candid interface and the HttpAgent
return Actor.createActor(idlFactory, {
agent,
canisterId,
...options?.actorOptions,
});
};
/**
* A ready-to-use agent for the identity canister
* @type {import("@dfinity/agent").ActorSubclass<import("./identity.did.js")._SERVICE>}
*/
export const identity = createActor(canisterId);
Create an actor for calling the identity service.
If you only have the candid file, you can generate a did.js file using the dfx tool, but this method is relatively cumbersome. A simpler way is to use the official didc tool.
Automatic installation script: (copy and save as a sh file to run)
unameOut="$(uname -s)"
case "${unameOut}" in
Linux*) machine=Linux;;
Darwin*) machine=Mac;;
*) machine="UNKNOWN:${unameOut}"
esac
release=$(curl --silent "https://api.github.com/repos/dfinity/candid/releases/latest" | grep -e '"tag_name"' | cut -c 16-25)
if [ ${machine} = "Mac" ]
then
echo "Downloading didc for Mac to ~/bin/didc"
curl -fsSL https://github.com/dfinity/candid/releases/download/${release}/didc-macos > /usr/local/bin/didc
elif [ ${machine} = "Linux" ]
then
echo "Downloading didc for Linux to ~/bin/didc"
curl -fsSL https://github.com/dfinity/candid/releases/download/${release}/didc-linux64 > ~/bin/didc
else
echo "Could not detect a supported operating system. Please note that didc is currently only supported for Mac and Linux"
fi
date
After installation, type didc bind ./identity.did -t js > ./identity.did.js to generate the did.js file (didc bind ./identity.did -t ts > ./identity.did.d.ts for the ts version).
How to Use Internet Identity Service#
Internet Identity (II) is a DID service officially launched by Dfinity, based on WebAuth. Applications on Dfinity generally support II login.
If you want to debug II in your local development environment, you need to clone Internet Identity to your local machine and deploy it to your local dfx network environment for development.
git clone [email protected]:dfinity/internet-identity.git
cd internet-identity
dfx start --clean
It is recommended to start with the --clean parameter because the default canister ID of the II service is the same as the default ID of the local wallet. Therefore, clean up the environment first to avoid conflicts. Note that since multiple dfx networks can be started locally, you must ensure that the network where II is deployed is the same as the project's network (same port).
npm install
II_ENV=development dfx deploy --no-wallet --argument '(null)'
This completes the local deployment of II.
Open package.json to ensure you have installed @dfinity/auth-client and @dfinity/authentication.
Below is the code for the frontend to call the II service.
const init = async () => {
authClient = await AuthClient.create();
await authClient.login({
maxTimeToLive: BigInt("0x7f7f7f7f7f"),
identityProvider:
"http://localhost:8000/?canisterId=rwlgt-iiaaa-aaaaa-aaaaa-cai",
onSuccess: async () => {
handleAuthenticated(authClient);
},
});
}
This code is also very easy to understand. First, it creates an auth client, then calls the login method.
maxTimeToLive sets the validity period of the delegated key, and identityProvider is the canister where II is deployed. If on the mainnet, it would be identity.ic0.app, and onSuccess is the callback function after authentication is completed. There are many other parameters that can be specified; for specifics, you can refer to Agent JS Docs, which will not be elaborated here.
Next, let's discuss how to initiate authenticated calls. In the previous Hello World example, we discussed how to initiate calls, but it used randomly generated anonymous identities. Once the user completes authentication, we can obtain their identity. How do we use the user's identity to initiate authenticated calls? As follows, pass the identity when creating the agent.
async function handleAuthenticated(authClient) {
identity = await authClient.getIdentity();
const agent = new HttpAgent({
identity: identity,
host: "http://localhost:8000",
});
// During local development, you need to fetch the Root Key
if(process.env.NODE_ENV !== "production") await agent.fetchRootKey();
let actor = Actor.createActor(idlFactory, {
agent,
canisterId: canisterId,
});
const greeting = await actor.greet(name);
}