Introducing a simplified developer workflow

The SDK Developer Workflow Preview release includes a preview of a simplified developer workflow. As part of our developer community, we encourage you to try out this new workflow and provide us with feedback on your experience.

The new developer workflow is intended to streamline the development process and make it easier for you to iterate quickly on your application design and implementation.

Before you begin

The SDK Developer Workflow Preview release is built from the same code base as the publicly-available release of the DFINITY Canister Software Development Kit (SDK). However, this version of the software includes features and changes that are not yet supported and might be known to be incomplete or unstable. In addition, the SDK Developer Workflow Preview release is not intended to work with any existing projects you might have previously compiled or deployed.

If possible, you should install the SDK Developer Workflow Preview preview release in a completely clean environment with no other versions of the DFINITY Canister Software Development Kit (SDK) installed. For information about removing the current software before installing a new release, see Removing the software before continuing to Download and install the SDK Developer Workflow Preview release.

Before you download and install the SDK Developer Workflow Preview, 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 stopped any Internet Computer network processes running on the local computer.

Getting started

To provide feedback on the simplified developer workflow, you must have the not publicly promoted version of the SDK Developer Workflow Preview available on your local computer.

Download and install

To download the SDK Developer Workflow Preview, you must specify the version using an environment variable.

To download and install:

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

    For example, open Applications, Utilities, then double-click Terminal or press +spacebar to open Search, then type terminal.

  2. Download and install the SDK Developer Workflow Preview by running the following command:

    sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"
  3. Type y and press Return to accept the license agreement and continue with the installation.

  4. Verify the SDK Developer Workflow Preview is ready to use by running the following command:

    dfx --version

    The command displays version information for the developer command-line interface similar to the following:

    dfx 0.6.12
  5. Preview usage information for the developer command-line interface (dfx) commands by running the following command:

    dfx --help

Create and deploy Hello, World

After you have downloaded and installed the SDK Developer Workflow Preview, you are ready to create and deploy the default sample application.

The default application consists of one greet function that accepts one text argument and returns the result in a terminal or in a browser.

To create your first application:

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

  2. Create a new project by running the following command:

    dfx new workflow_hello

    The dfx new workflow_hello command creates a new project directory with template files and a new Git repository for your project.

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

    cd workflow_hello
  4. Start the Internet Computer network locally on your computer by running the following command:

    dfx start --background
  5. Register, build, and deploy all of the canisters specified in the default dfx.json file by running the following command:

    dfx deploy

    If you have access to the Internet Computer running remotely, you can deploy to the that network instead of deploying locally by specifying the --network option and the network alias configured in the dfx.json file. For example, you would run a command similar the following:

    dfx deploy --network ic

    If prompted, specify the credentials for accessing the Internet Computer.

    The dfx deploy command output displays information about the operations it performs.

  6. Call the predefined greet function in the program by running the following command:

    dfx canister call workflow_hello greet '("World")'

    The command displays the following output for the greet function:

    ("Hello, World!")
  7. Copy the canister identifier for the workflow_hello_assets canister and paste it into a browser to test the greet function front-end.

    If you are using the default local host and port, you should have a URL similar to the following:

    http://127.0.0.1:8000/?canisterId=cxeji-wacaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q
  8. Copy the canister identifier for the workflow_hello canister and paste into a browser using the default local host and port to test the greet function using the Candid web interface.

    If you are using the default local host and port, you should have a URL similar to the following:

    http://127.0.0.1:8000/candid?canisterId=75hes-oqbaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q

    After testing the functions, return to the terminal that displays network operations to stop the Internet Computer network.

  9. Press Control-C to interrupt the local network process.

  10. Stop the local Internet Computer network by running the following command:

    dfx stop

Deploying a second application

The Hello, World example illustrates the basic workflow using a simple predefined sample application. For a more realistic view of the development process, let’s build a second application from scratch.

To keep things simple, let’s write a program that is similar to the default sample application but introduces a few new functions and data types.

Create a second application

To create a second sample application:

  1. Open a new terminal shell and navigate to the working directory you use for Internet Computer projects.

  2. Create a new project by running the following command:

    dfx new my_counter_hello
  3. Change to your project directory by running the following command:

    cd my_counter_hello

Modify the default source code

To replace the default application application:

  1. Open the src/my_counter_hello/main.mo file in a text editor and delete the existing content.

    The new program uses a function in the Motoko base library for natural numbers, so the first step is to import the Nat module.

  2. Add an import statement as the first line in your new program:

    import Nat "mo:base/Nat";
  3. Add variable declarations for count as a natural number and output as text:

    var count: Nat = 0;
    var output : Text = "Welcome to the simplified developer preview, ";

    In the next step, we’ll create an actor with two simple functions—whoami and get—to display a welcome message that takes a text argument and to increment a counter.

  4. Copy and paste the following sample code into the main.mo file:

    actor HelloActor {
    
       public func whoami(name: Text) : async Text {
          count += 1;
          return output # name # ": " # Nat.toText(count)
       };
    
       public query func get() : async Text {
          return "Your counter value is: " # Nat.toText(count);
       };
    };

    In this code sample:

    • The whoami function increments a counter using the count +=1 expression. This operation is a state change, so the whoami function is an update call.

    • The get function is only used to retrieve the counter value without making any changes to state, so the get function is a query call.

    • The actor returns text, so both the whoami and get functions use the Nat.toText function to convert the count variable to text.

    Query calls return results faster. In designing an application, you should consider where a query call might make your program more efficient. For more information about the difference between update and query calls, see Canisters include both program and state.

    If you want to copy and paste the whole program at once, it looks like this:

    import Nat "mo:base/Nat";
    
    var count: Nat = 0;
    var output : Text = "Welcome to the simplified developer preview, ";
    
    actor HelloActor {
    
       public func whoami(name: Text) : async Text {
          count += 1;
          return output # name # ": " # Nat.toText(count)
       };
    
       public query func get() : async Text {
          return "Your counter value is: " # Nat.toText(count);
       };
    };
  5. Save your changes and close the modified main.mo file.

Deploy the application

To deploy the application:

  1. Start the Internet Computer network locally on your computer by running the following command:

    dfx start --background
  2. Register, build, and deploy all of the canisters specified in the default dfx.json file by running the following command:

    dfx deploy my_counter_hello

    In this case, we specify a canister name to register, build, and deploy because we haven’t added any front-end code to the project.

Test the application in a terminal

To test the application in a terminal:

  1. Call the whoami function with your name as an argument by running a command similar to the following:

    dfx canister call my_counter_hello whoami '("YOUR-NAME")'

    The command displays output similar to the following:

    ("Welcome to the simplified developer preview, Jane: 1")

    Repeat the call the whoami function a few times to see the counter value increment.

  2. Call the get function by running the following command:

    dfx canister call my_counter_hello get

    The command displays output similar to the following:

    ("Your counter value is: 3")

Test functions in a browser

To test the application in a browser:

  1. Copy the canister identifier for the my_counter_hello canister.

  2. Open a browser and navigate to the default host name and port.

  3. Add the candid endpoint followed by canisterId+ and the canister identifier for the my_counter_hello canister.

    If you are using the default local host and port, you should have a URL similar to the following:

    http://127.0.0.1:8000/candid?canisterId=75hes-oqbaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q
  4. Type a name for the whoami function, then click Call to see the result.

  5. Delete the text from the whoami function, then click Lucky to generate a random text value and see the result.

  6. Click Query for the get function.

Stop the local network

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 local Internet Computer network by running the following command:

    dfx stop

Command-line reference

The SDK Developer Workflow Preview introduces the following new dfx subcommand:

command Description

deploy

Deploys all or a specific canister from the code in your project. By default, all canisters are deployed.

Basic usage

dfx deploy [flag] [option] [--all | canister_name]

Flags

You can use the following optional flags with the dfx deploy command.

Flag Description

-h, --help

Displays usage information.

-V, --version

Displays version information.

Options

You can specify the following option for the dfx deploy command.

Option Description

--network <network>

Overrides the network to connect to. By default, the local network is used.

Arguments

You can specify the following arguments for the dfx deploy command.

Argument Description

canister_name

Specifies the name of the canister you want to register, build, and deploy. Note that the canister name you specify must match at least one name in the canisters section of the dfx.json configuration file for the project. If you don’t specify a canister name, dfx deploy will deploy all canisters defined in the dfx.json file.

Next steps and how you can help

This SDK Developer Workflow Preview touched on only a few key steps to introduce the simplified developer workflow.

After you have experimented with the SDK Developer Workflow Preview and the tutorial examples in this document, we would love to hear from you.

Our key questions are:

  • How would you rank your experience with the new workflow compared to the current workflow on a scale of one (I don’t see why you would change what you have!) to ten (Please implement this as soon as possible!)’

  • Do you have suggestions for improving either this new workflow or the existing workflow?

  • What is the single most important thing we should change that would improve the experience of building apps for the Internet Computer?

If you want to provide feedback, let us know what you think on the DFINITY Developer Forum or send us a message using the support email address.