Exploring the default project

If you started your tour of the DFINITY Canister Software Development Kit (SDK) with the Quick start, you have already seen the basic work flow for creating applications that run on the Internet Computer. Now, let’s take a closer look at that work flow by exploring the default files and folders that are added to your workspace when you create a new project.

As a preview, the following diagram illustrates the development work flow when running the Internet Computer locally on you computer.

Development work flow

Before you begin

Before you start this tutorial, verify the following:

  • You have an internet connection and access to a shell terminal on your local macOS or Linux computer.

  • You have node.js installed if you want to include the default template files for front-end development in your project.

  • You have downloaded and installed the DFINITY Canister SDK package as described in Download and install.

  • You have installed the Visual Studio Code plugin for Motoko as described in Install the language editor plug-in if you are using Visual Studio Code as your IDE.

  • You have stopped any Internet Computer network processes running on the local computer.

Create a new project

As discussed in the Quick start, applications for the Internet Computer start as projects that you create projects using the dfx executable command-line interface (CLI). . To take a closer look at the files and folders that are included in a project by default, let’s create a new project to work with.

To create a new project:

  1. Open a terminal shell on your local computer, if you don’t already have one open.

  2. Create a folder for your Internet Computer sample projects in your home directory by running the following command:

    mkdir ~/ic-projects
  3. Change to your sample projects folder. For example:

    cd ~/ic-projects
  4. Create a new project by running the following command:

    dfx new explore_hello

    The dfx new explore_hello command creates a new explore_hello project, including a default project directory structure under the new project name and a new Git repository for your project. If you have node.js installed locally, creating a new project also adds some template front-end code and dependencies.

    To ensure that project names are valid when used in JavaScript, Motoko, and other contexts, you should only use alphanumeric characters and underscores. You cannot include dashes or any special characters.

    The command displays output similar to the following excerpt:

    Fetching manifest https://sdk.dfinity.org/manifest.json
    Creating new project "explore_hello"...
    CREATE       explore_hello/src/explore_hello/main.mo (107B)...
    CREATE       explore_hello/dfx.json (320B)...
    CREATE       explore_hello/.gitignore (189B)...
    CREATE       explore_hello/README.md (1.01KB)...
    CREATE       explore_hello/src/explore_hello/public/index.js (155B)...
    CREATE       explore_hello/package.json (263B)...
    CREATE       explore_hello/webpack.config.js (1.76KB)...
  5. View the default directory structure by running the following command:

    ls -l explore_hello

    By default, the project directory structure includes at least one source subdirectory, a template README.md file, and a default dfx.json configuration file.

    Depending on whether you have node.js installed, your project directory might include some or all of the following files:

    explore_hello/
    ├── README.md      # default project documentation
    ├── dfx.json       # project configuration file
    ├── node_modules   # libraries for front-end development
    ├── package-lock.json
    ├── package.json
    ├── src            # source files directory
    |   └── explore_hello
    │       ├── main.mo
    │       └── public
    │           └── index.js
    └── webpack.config.js

    At a minimum, the default project directory includes the following folders and files:

    • A default README file for documenting your project in the repository.

    • A default dfx.json configuration file to set configurable options for your project.

    • A default src directory for all of the source files required by your application.

    The default src directory includes a template main.mo file that you can modify or replace to include your core programming logic.

    Because this tutorial focuses on the basics of getting started, you are only going to use the main.mo file. If you have node.js installed, your project directory includes additional files and directories that you can use to define the front-end interface for your application. Front-end development and the template files in the public folder are discussed a little later.

Review the default configuration

By default, creating a new project adds some template files to your project directory. You can edit these template files to customize the configuration settings for your project and to include your own code to speed up the development cycle.

To review the default configuration file for your project:

  1. Open a terminal shell on your local computer, if you don’t already have one open.

  2. Change to your project directory by running the following command:

    cd explore_hello
  3. Open the dfx.json configuration file in a text editor to review the default settings.

    For example:

    {
      "canisters": {
        "explore_hello": {
          "main": "src/explore_hello/main.mo",
          "type": "motoko"
        },
        "explore_hello_assets": {
          "dependencies": [
            "explore_hello"
          ],
          "frontend": {
            "entrypoint": "src/explore_hello_assets/public/index.js"
          },
          "source": [
            "src/explore_hello_assets/assets",
            "dist/explore_hello_assets/"
          ],
          "type": "assets"
        }
      },
      "defaults": {
        "build": {
          "packtool": ""
        }
      },
      "dfx": "0.6.9",
      "networks": {
        "local": {
          "bind": "127.0.0.1:8000",
          "type": "ephemeral"
        },
        "tungsten": {
          "providers": [
            "https://gw.dfinity.network"
          ],
          "type": "persistent"
        }
      },
      "version": 1
    }

    Let’s take a look at a few of the default settings.

    • The canisters section specifies the name of the WebAssembly module for your explore_hello project is explore_hello.

    • The canisters.explore_hello key specifies that the main program to be compiled is located in the path specified by the main setting, in this case, src/explore_hello/main.mo and the type setting indicates that this is a motoko program.

    • The canisters.explore_hello_assets key specifies configuration details about front-end assets for this project. Let’s skip those for now.

    • The dfx setting is used to identify the version of the software used to create the project.

    • The networks section specifies information about the networks to which you connect. The default settings bind the local Internet Computer network to the local host address 127.0.0.1 and port 8000.

      If you have access to other Internet Computer network providers, the networks section can include network aliases and URLs for connecting to those providers.

    You can leave the default settings as they are.

  4. Close the dfx.json file to continue.

Review the default program code

New projects always include a template main.mo source code file. You can edit this file to include your own code to speed up the development cycle.

Let’s take a look at the sample program in the default main.mo template file as a starting point for creating simple program using the Motoko programming language.

To review the default sample program for your project:

  1. Check that you are still in your project directory by running the following command:

    pwd
  2. Open the src/explore_hello/main.mo file in a text editor and review the code in the template:

    actor {
        public func greet(name : Text) : async Text {
            return "Hello, " # name # "!";
        };
    };

    Let’s take a look at a few key elements of this program:

    • You might notice that this sample code defines an actor instead of a main function, which some programming languages require. For Motoko, the main function is implicit in the file itself.

    • Although the traditional "Hello, World!" program illustrates how you can print a string using a print or println function, that traditional program would not represent a typical use case for Motoko programs that run on the Internet Computer.

    • Instead of a print function, this sample program defines an actor with a public greet function that takes a name argument with a type of Text.

    • The program then uses the async keyword to indicate that the program returns an asynchronous message consisting of a concatenated text string constructed using "Hello, ", the # operator, the name argument, and "!".

    We’ll explore code that uses actor objects and asynchronous message handling more a little later. For now, you can continue to the next section.

  3. Close the main.mo file to continue.

Start the local network

Before you can build the default project, you need to connect to the Internet Computer network either running locally in your development environment or running remotely on a sub-network that you can access.

As a best practice, this step requires you to have two terminal shells open, so that you can start and see network operations in one terminal and manage your project in another.

To start the network locally:

  1. Open a new terminal window or tab on your local computer and navigate to your project directory.

    For example, you can do either of the following if running Terminal on macOS:

    • Click Shell, then select New Tab to open a new terminal in your current working directory.

    • Click Shell and select New Window, then run cd ~/ic-projects/explore_hello in the new terminal if your explore_hello project is in the ic-projects working folder.

    You should now have two terminals open with your project directory as your current working directory.

  2. Start the Internet Computer network on your local computer by running the following command:

    dfx start

    Depending on your platform and local security settings, you might see a warning displayed. If you are prompted to allow or deny incoming network connections, click Allow.

    After you start the local network, you have one terminal that displays messages about network operations and another for performing project-related tasks.

  3. Leave the terminal that displays network operations open and switch your focus to the terminal where you created your new project.

Register canister identifiers

After you connect to the Internet Computer network running locally in your development environment, you can register with the network to generate unique, network-specific canister identifiers for your project.

To register canister identifiers for the local network:

  1. Check that you are still in your project directory, if needed.

  2. Register unique canister identifiers for the canisters in the project by running the following command:

    dfx canister create --all

    The command displays the network-specific canister identifiers for the canisters defined in the dfx.json configuration file.

    "explore_hello" canister created with canister id: "75hes-oqbaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q"
    "explore_hello_assets" canister created with canister id: "cxeji-wacaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q"

    Because you are connected to the Internet Computer network running locally, these canister identifiers are only valid locally and are stored for the project in the .dfx/local/canister_ids.json file.

    For example:

    {
      "explore_hello": {
        "local": "75hes-oqbaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q"
      },
      "explore_hello_assets": {
        "local": "cxeji-wacaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q"
      }
    }

Build the program

Now that you have explored the default configuration settings and program code and have started the Internet Computer network, let’s compile the default program into an executable WebAssembly module.

To build the program executable:

  1. In the terminal shell on your local computer, navigate to your explore_hello project directory.

    You must run the dfx build command from within the project directory structure.

  2. Build the executable canister by running the following command:

    dfx build

    You should see output similar to the following:

    Building canisters...
    Building frontend...

    Because you are connected to the Internet Computer network running locally, the dfx build command adds the canisters directory under the .dfx/local/ directory for the project. For example:

  3. Verify that the canisters/explore_hello directory created by the dfx build command contains the WebAssembly and related application files by running the following command.

    ls -l .dfx/local/canisters/explore_hello/

    For example, the command returns output similar to the following:

    -rw-r--r--  1 pubs  staff     43 Jul 21 12:18 explore_hello.did
    -rw-r--r--  1 pubs  staff    103 Jul 21 12:18 explore_hello.did.js
    -rw-r--r--  1 pubs  staff    174 Jul 21 12:18 explore_hello.js
    -rw-r--r--  1 pubs  staff  95905 Jul 21 12:18 explore_hello.wasm

    The canisters/explore_hello directory contains the following key files:

    • The explore_hello.did file contains an interface description for your main program.

    • The explore_hello.did.js file contains a JavaScript representation of the canister interface for the functions in your program.

    • The explore_hello.js file contains a JavaScript representation of the canister interface for your program.

    • The explore_hello.wasm file contains the compiled WebAssembly for the assets used in your project.

    The canisters/explore_hello_assets directory contains similar files to describe the front-end assets associated with your project.

    In addition to the files in the canisters/explore_hello and the canisters/explore_hello_assets directories, the dfx build command creates an idl directory.

Deploy the project locally

You’ve seen that the dfx build command creates several artifacts in a canisters directory for your project. The WebAssembly modules and the canister_manifest.json file are required for your program to be deployed on the Internet Computer network.

To deploy locally:

  1. In a terminal shell on your local computer, navigate to your explore_hello project directory.

  2. Deploy your explore_hello project on the local network by running the following command:

    dfx canister install --all

    The command displays output similar to the following:

    Installing code for canister explore_hello, with canister_id 75hes-oqbaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q
    Installing code for canister explore_hello_assets, with canister_id cxeji-wacaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q
  3. Call the predefined greet function in the program by running the following command:

    dfx canister call explore_hello greet everyone

    This example uses the dfx canister call command to pass "everyone" as an argument of type string to the greet function.

  4. Verify the command displays the return value of the greet function.

    For example:

    ("Hello, everyone!")

View the default front-end

If you have node.js installed in your development environment, your project includes a simple front-end example that uses a template index.js JavaScript file for accessing the explore_hello program in a browser.

To explore the default front-end template:

  1. Open a terminal shell on your local computer, if you don’t already have one open, and navigate to your explore_hello project directory.

  2. Open the src/explore_hello_assets/public/index.js file in a text editor and review the code in the template script:

    import explore_hello from 'ic:canisters/explore_hello';
    
    explore_hello.greet(window.prompt("Enter your name:")).then(greeting => {
      window.alert(greeting);
    });

    The template index.js file uses the Document Object Model (DOM) to describe the structure and content of a document on the web.

    This sample file imports the canister you created and calls the greet function in a prompt window.

  3. Close the index.js file to continue.

  4. View the front-end assets created for the project by running following command:

    ls -l .dfx/local/canisters/explore_hello_assets/

    The command displays output similar to the following:

    total 576
    drwxr-xr-x  5 pubs  staff     160 Jul 21 12:18 assets
    -r--r--r--  1 pubs  staff     131 Dec 31  1969 assetstorage.did
    -r--r--r--  1 pubs  staff  135497 Dec 31  1969 assetstorage.wasm
    -rw-rw-rw-  1 pubs  staff     131 Dec 31  1969 explore_hello_assets.did
    -rw-r--r--  1 pubs  staff     215 Jul 21 12:18 explore_hello_assets.did.js
    -rw-r--r--  1 pubs  staff     181 Jul 21 12:18 explore_hello_assets.js
    -rw-rw-rw-  1 pubs  staff  135497 Dec 31  1969 explore_hello_assets.wasm

    These files were generated automatically by the dfx build command using node modules and the template index.js file.

  5. Open a browser and navigate to the local network address and port number—127.0.0.1:8000/—specified in the dfx.json configuration file.

    To specify the canister you want the web server to display, add the canisterId parameter and the explore_hello_assets canister identifier to the URL using the following syntax:

    ?canisterId=<YOUR-CANISTER-IDENTIFIER>

    For example, the full URL should look similar to the following:

    http://127.0.0.1:8000/?canisterId=cxeji-wacaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q
    You must use the case-sensitive canisterId parameter before the canister identifier.
  6. Verify that you are prompted to type a greeting.

    For example:

    Hello world prompt window

  7. Type a greeting, then click OK to return the greeting.

    For example:

    Hello world return string

  8. Click OK to close the pop-up alert window.

Stop the local network

After you finish experimenting with your program, you can stop the local Internet Computer network so that it doesn’t continue running in the background.

To stop the local network:

  1. In the terminal that displays network operations, press Control-C to interrupt the local network process.

  2. Stop the Internet Computer network by running the following command:

    dfx stop