Shortening dfx commands into a single script that's executable

Developers
1

I recently had a discussion with some of my colleagues on how we can shorten DFX commands into scripts that are executable by just writing down one single command.

This is specifically for tasks requiring someone to run multiple commands to achieve a particular end goal.

One good example is when you want to do a canister upgrade.

Example for backend:

  • You have to run a command to build your project to generate the latest wasm file,
  • You then need to fetch the wasm path & the canister id
  • Then run the command for upgrading the canister using the latest wasm path and canister

Example for frontend:

  • You build the frontend canister
  • You then run a command for upgrading the canister

If you’re a developer running these commands frequently as you upgrade your canister, you’ll get tired of it

What if you just run a single command that executes everything for you?

I came up with a script (for my personal use to be precise) that helps me do this

When upgrading your canister, there’s no need to go through all those steps. Just run the script

For frontend:

npx canister-upgrader <canister_name> --frontend --mainnet

For backend:

npx canister-upgrader <canister_name> --backend --mainnet

You can also remove the flag --mainnet If you’re just doing it locally
i.e

Frontend:

npx canister-upgrader <canister_name> --frontend

Backend:

npx canister-upgrader <canister_name> --backend

I thought it wise to put it here just in case someone needs to use them, thanks!

You can check out the package here

1 Like
2

I’ve managed to update the package

Now it supports:

  • Automated canister upgrade process
  • Candid (.did) file generation for Rust canisters
  • Support for both local and mainnet deployments
  • Handles both frontend and backend canisters

You can install the tool using the command

npm install -g canister-tools

Check it out at npmjs.com

Updated documentation:

Tools Available

1. Candid File Generator:

Automatically generates .did files for Rust canisters.

Usage:

npx generate-did <canister_name>

Example:

generate-did backend

This will:

  1. Build the Rust canister
  2. Extract and generate the Candid file
  3. Save it as <canister_name>.did

2. Canister Upgrader:

Streamlines the process of upgrading Internet Computer canisters.

Frontend Canister Upgrades

Local Development:

upgrade-canister <frontend_canister_name> --frontend

Mainnet Deployment:

upgrade-canister <frontend_canister_name> --frontend --mainnet

Backend Canister Upgrades

Local Development:

upgrade-canister <backend_canister_name> --backend

Mainnet Deployment:

upgrade-canister <backend_canister_name> --backend --mainnet

How It Works:

Frontend Upgrade Process

  • Builds the canister
  • Performs the upgrade installation
  • Handles network-specific configurations

Backend Upgrade Process

  • Builds the canister
  • Locates the correct Wasm file
  • Fetches the canister ID

Executes the upgrade with proper network paths

Command Options

Options: 
--frontend, Upgrade a frontend canister 
--backend, Upgrade a backend canister 
--mainnet, Deploy to mainnet (IC network) 
--help Show help information

Requirements

  • Node.js installed
  • DFX CLI installed
  • ICP project setup
3 Likes
3

Glad to see people propose other interfaces and building tooling other than just complaining about dfx :slightly_smiling_face:

Potentially stupid question: What is the difference between your upgrade-canister and dfx deploy? Is it just different command names/order or something bigger?

2 Likes
4

Welcome!

Haha that’s a good question. Personally, I was struggling to re-deploy canisters that were using stable memory in rust to mainnet. Cause I had to run these commands manually:

  • dfx build <canister_name> --network ic
  • find . -name "<canister_name>.wasm"
  • dfx canister id <canister_name> --network ic
  • dfx canister --network ic install <canister_id> --mode upgrade --wasm .dfx/ic/canisters/<canister_name>/<canister_name>.wasm

Whenever I used dfx deploy, I had issues preserving the state. So I had to compile all those commands above into a single script so that I can easily excecute them using my command

upgrade-canister <backend_canister_name> --backend --mainnet

For the frontend command, upgrade-canister <frontend_canister_name> --frontend the reason I had to make it is cause everytime I’d do dfx deploy <frontend_canister_name> it would also re-deploy my backend canister if they’re in the same project directory, thus loosing the backend canister’s state.

So I had to compile these dfx commands since they were the only way I could do it without erasing the backends data if they’re in the same project directory

  • dfx build frontend_canister_name --network ic
  • dfx canister install frontend_canister_name --mode upgrade --network ic
1 Like
5

I just realized an easy way for this is using GitHub actions, especially when it comes to re-deployment :thinking: