Setup

In this section, we will help you set up the boilerplate code for our project. By the end of this section, you'll have a development environment pre-configured with all the necessary tools and dependencies, and you'll be ready to start building your canisters.

Preparing your Development Environment

You can set up your development environment either locally on your machine or in the cloud using GitHub Codespaces.

Option 1: Using GitHub Codespaces

GitHub Codespaces provides a complete, ready-to-use dev environment in your browser. It saves you from the need for local setup, allowing you to concentrate on learning and building.

To create a new Codespace with the boilerplate, go to the ICP-azle-boilerplate repository.

Next, click on the "Code" button, then select "Create codespace on main". This action will generate a new Codespace, pre-configured with everything you need to start building this project.

Please note that the first time you open the Codespace, the dependencies for this project will be installed automatically. This process may take a few minutes, but you can monitor the installation progress in the terminal.

Option 2: Setting up Locally

If you prefer to set up your development environment locally, start by navigating to the ICP-azle-boilerplate repository. Select the "Code" button, then the "Local" tab, and copy the repository's URL.

In your terminal, navigate to the directory where you want to store your project, then clone the repository to your local machine by running:

bashDownloadCopy code
git clone https://github.com/dacadeorg/ICP-azle-boilerplate.git `

Next, move into the cloned repository's directory with:

bashDownloadCopy code
cd ICP-azle-boilerplate

Finally, install the project's dependencies by running:

bashDownloadCopy code
npm install

This command will install all the necessary dependencies for the project. Once the installation is complete, you're ready to start building your canisters!

Preparing Our Terminal

In this section, we will prepare our terminal environment by installing key tools: Node Version Manager (nvm) and DFX. Please note that the following instructions are specifically for Unix-like systems such as Linux and macOS. If you're on a Windows system, you would need to set up the Windows Subsystem for Linux (WSL) to follow along, or alternatively, you could use GitHub Codespaces. Let's get started.

1. Install Node Version Manager (nvm): Nvm is a useful tool that allows for the management of multiple active Node.js versions. With nvm, switching between different Node.js versions is a breeze. For this tutorial, we'll utilize Node.js version 18. To install nvm, execute the following command in your terminal:

bashDownloadCopy code
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

2. Switch to Node.js version 18: Node.js is a JavaScript runtime that enables the execution of JavaScript outside of a browser environment, and it's necessary for running our Azle project. To switch to Node.js version 18 using nvm, use the following command:

bashDownloadCopy code
nvm use 18

3. Install DFX: DFX is the command-line interface for the Internet Computer, and we'll use it to create our Azle project. To install DFX, execute this command:

bashDownloadCopy code
DFX_VERSION=0.14.1 sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"

4. Add DFX to your path: Add DFX to your PATH: Now that DFX is installed, we need to add it to our system's PATH. This allows us to execute DFX commands from any location within the terminal. Run this command to add DFX to your PATH:

bashDownloadCopy code
echo 'export PATH="$PATH:$HOME/bin"' >> "$HOME/.bashrc"

5. Reload your terminal (if using GitHub Codespaces): Reload your terminal (if using GitHub Codespaces): If you're using GitHub Codespaces for this tutorial, you'll need to reload your terminal to ensure all changes are properly applied. You can do this by clicking on the "Reload" button located in the top-right corner of your terminal.

Understanding the Boilerplate Code

The boilerplate code we've prepared serves as a basic Azle project. It is designed to help you get started quickly by providing the necessary configuration files and dependencies. This code also includes a simple canister that serves as a reference for constructing your own canisters. Let's explore its key components:

1. TypeScript Configuration File (tsconfig.json): Located in the root directory of your project, this file sets up the TypeScript compiler options. Here is what it looks like:

jsonDownloadCopy code
{
  "compilerOptions": {
    "strict": true,
    "target": "ES2020",
    "experimentalDecorators": true,
    "strictPropertyInitialization": false,
    "moduleResolution": "node",
    "allowJs": true,
    "outDir": "HACK_BECAUSE_OF_ALLOW_JS",
    "allowSyntheticDefaultImports": true
  }
}

You can learn more about these options in the TypeScript documentation.

2. DFX Configuration File (dfx.json): Also in the root directory, this file configures DFX and includes the following:

jsonDownloadCopy code
{
  "canisters": {
    "message_board": {
      "type": "custom",
      "build": "npx azle message_board",
      "root": "src",
      "ts": "src/index.ts",
      "candid": "src/index.did",
      "wasm": ".azle/message_board/message_board.wasm.gz"
    }
  }
}

This configuration file communicates vital aspects of your canister to the DFINITY SDK (dfx). Here, we're creating a message_board canister using the Azle framework. Let's break down the properties:

• "canisters": The parent property for defining our canister, message_board in this case.
• "message_board": The name of our canister, used for interacting with it.
• "type": Describes the framework/language that is used in this canister. It can be Rust, Motoko, or custom (for Azle).
• "build": Instructs DFX to use the Azle CLI to build the message_board canister.
• "root" and "ts": Direct DFX to the src folder and src/index.ts file respectively for our code.
• "candid": Points DFX to our Candid file (src/index.did), an interface description language (IDL) used by Internet Computer.
• "wasm": Directs DFX to our compiled WebAssembly (WASM) file (.azle/message_board/message_board.wasm.gz), a fast, efficient, and secure binary instruction format.

3. Package.json File: The package.json file in the root directory manages the project's metadata and dependencies.

jsonDownloadCopy code
  "name": "dfinity_project",
  "main": "index.js",
  "dependencies": {
    "azle": "0.16.2",
    "uuid": "^9.0.0"
  },
  "engines": {
    "node": "^12 || ^14 || ^16 || ^18"
  },
  "devDependencies": {
    "@types/uuid": "^9.0.1"
  }

This file is crucial for managing the project's dependencies and scripts. It contains information about the project such as its name, version, and main file. It also lists the dependencies and devDependencies needed for the project, specifying their versions:

• "azle": Azle is a framework for building decentralized applications on the Internet Computer. It provides tools and abstractions that make it easier to write, deploy, and interact with canisters.

• "uuid": The uuid package is a popular JavaScript library for creating unique identifiers. This could be used in your application for any purpose where you need a unique ID, such as creating unique identifiers for users, orders, or other entities.

• The scripts section includes commands that can be run from the terminal, while the engines section specifies the versions of Node.js that the project is compatible with.