Dojo Web Starter: Official Guide

The official Dojo Starter guide, the quickest and most streamlined way to get your Dojo Autonomous World up and running. This guide will assist you with the initial setup, from cloning the repository to deploying your world.

The Dojo Starter contains the minimum required code to bootstrap your Dojo Autonomous World. This starter package is included in the dojoup binary. For more detailed instructions, please refer to the official Dojo Book here.

Prerequisites

• Rust - install here
• Cairo language server - install here

Step-by-Step Guide

Follow the steps below to setup and run your first Autonomous World.

Step 1: Install dojoup

Start by installing dojoup. This cli tool is a critical component when building with Dojo. It manages dependencies and helps in building your project. Run the following command in your terminal:

curl -L https://install.dojoengine.org | bash
dojoup

The command downloads the dojoup installation script and executes it.

Step 2: Clone the Repository

The next step is to clone the repository to your local machine. Open your terminal and type the following command:

git clone https://github.com/coostendorp/dojo-web-starter && cd dojo-web-starter

This command will create a local copy of the Dojo Web Starter repository and enter the project directory.

Step 3: Build the Example World

With dojoup installed, you can now build your example world using the following command:

make build

This command compiles your project and prepares it for execution.

Step 4: Start Katana RPC

Katana RPC is the communication layer for your Dojo World. It allows different components of your world to communicate with each other. To start Katana RPC, use the following command:

katana --allow-zero-max-fee

Step 5: Migrate (Deploy) the World

Finally, deploy your world using the sozo migrate command. This command, deploys your world to Katana!

make deploy

Step 6: Get the React frontend ready

make prep_web
cd web
yarn

Step 7: Run the frontend locally

cd web
yarn dev

Project Structure

This is an overview of the most important folders/files:

• Makefile : A collection of helpful commands, mainly for Dojo
• contracts : The Dojo Cairo smart contract code
  • src/components.cairo : Dojo component definitions
  • src/systems.cairo : Dojo component definitions
  • src/Scarb.toml : The scarb config file used for katana
• web : A Vite React project
  • .env : (copied from env.example) Contains the hardcoded developer addresses used for Dojo
  • src/dojo/contractComponents.ts : Client-side definitions of the components
  • src/dojo/createClientComponents.ts : Client-side setup of the components
  • src/dojo/createSystemCalls.ts : Client-side definitions of the systems

Typical development activities

Add a DOJO system

• Edit src/systems.cairo
• Edit src/dojo/createSystemCalls.ts

Add a DOJO component

• Edit src/components.cairo
• Edit src/dojo/contractComponents.ts
• Edit src/dojo/createClientComponents.ts

Redeploy to Katana

• Restart Katana
• Redeploy the contracts with make deploy or cd contracts && sozo migrate

Troubleshooting / Tricks

When using vscode, the cairo language server panics with thread 'main' panicked at 'internal error: entered unreachable code:

Resolution: None, this is a know issue, can ignore

When deploying/migrating, consistent exceptions even though the contract compiles.

Resolution: Delete the contracts/target dir

How do I use different accounts while testing?

Register 2 accounts (example from https://github.com/coostendorp/dojo-rps):

let player1 = starknet::contract_address_const::<0x1337>();
let player2 = starknet::contract_address_const::<0x1338>();

And then switch accounts like this:

starknet::testing::set_contract_address(player1);