Dojo.js enables simple, clean, and efficient syncing of your dojo world. Plus, it comes with burners and other handy utils for building the most complex of onchain applications.
If you are not familiar with Dojo, then you should read the book first.
Start a new react app with (You will need dojo installed):
npx @dojoengine/create-dojo start -t example-vite-react-sdk
This command initializes a new directory with the template alongside the
dojo-starter
Cairo app. It offers a streamlined way to explore Dojo from end to end, providing a comprehensive overview of its capabilities. Additionally, this setup serves as an excellent foundation for building the next big thing.
-
Terminal 1: Start the local Katana node
cd dojo-starter katana --disable-fee --allowed-origins "*"
-
Terminal 2: Build and migrate the Dojo starter
cd dojo-starter sozo build && sozo migrate apply # Start Torii indexer - world address can be found in the print out of migrate torii --world <WORLD_ADDRESS> --allowed-origins "*"
-
Terminal 3: Launch the frontend application
cd client pnpm i && pnpm dev
Note: Run each step in a separate terminal window to keep all processes running simultaneously.
Dojo.js provides an instant and easy way to interface with your world you can simply create a client. It exposes a familiar like query language to subscribe to and fetch entities. Read the SDK full documentation
pnpm i @dojoengine/sdk
Basic example: example-vite-react-sdk More complex: example-vite-kitchen-sink
// Create client with your parameters
const db =
(await init) <
Schema >
({
// your config
client: {
rpcUrl: dojoConfig.rpcUrl,
toriiUrl: dojoConfig.toriiUrl,
relayUrl: dojoConfig.relayUrl,
worldAddress: dojoConfig.manifest.world.address,
},
// allows typed messaging via indexer
domain: {
name: "Example",
version: "1.0",
chainId: "your-chain-id",
revision: "1",
},
},
// typed schema
schema);
// Query - fetch with a query then pipe into your state of choice
await db.getEntities(
{
dojo_starter: {
Moves: {
$: {
where: {
player: {
$eq: addAddressPadding(address),
},
},
},
},
},
},
(resp) => {
if (resp.error) {
console.error("resp.error.message:", resp.error.message);
return;
}
if (resp.data) {
// this uses a typed zustand store, but you can use whatever state you choose
state.setEntities(resp.data);
}
}
);
Dojo.js is modularized into small packages to keep it light.
Getting started, we recommend using the SDK package, which will provide you with a simple interface to work with:
- SDK: Clean abstraction incorporating other packages and providing the best way to get started
Read the SDK full documentation
Other packages:
- core: Dojo provider for an interface into your world
- create Burner: Create burners for local development fast
- react: React package of hooks for working with Dojo
- state: State package for compatible state managers (Currently RECS)
- torii-client: Client package for working with Torii WASM. This package exports all the types needed to build with torii-client.
- torii-wasm: WASM build
- utils: Helpful utils for working with Dojo apps
- utils-wasm: WASM utils for working with Dojo apps
Spin any of these examples locally
npx @dojoengine/create-dojo start
- example-vite-react-sdk
- example-vite-react-phaser-recs
- example-vite-react-pwa-recs
- example-vite-react-threejs-recs
- example-vue-app-recs
- example-vite-kitchen-sink
- example-nodejs-bot
Dojo.js is a work in progress. We welcome contributions! Here's how you can get started:
-
Clone the repository:
git clone https://github.com/dojoengine/dojo.js.git cd dojo.js
-
Install dependencies:
pnpm i
Before running examples, you need to build the packages:
-
Build all packages:
pnpm run build
-
Watch for changes (development mode):
pnpm run build --watch
To run the examples, you'll need to set up three terminal windows:
Terminal 1: Set up the Dojo starter environment
-
Navigate to the Dojo starter directory:
cd worlds/dojo-starter
-
Start Katana (local Starknet devnet) with fee disabled and all origins allowed:
katana --disable-fee --allowed-origins "*"
Terminal 2: Build, migrate, and run Torii
-
Navigate to the Dojo starter example:
cd examples/dojo-starter
-
Build and migrate the contracts:
sozo build sozo migrate
-
Run Torii (indexer) with the world address and allowed origins:
torii --world <WORLD_ADDRESS> --allowed-origins "*"
Note: The world address may change. Ensure you're using the correct address from your migration output.
Terminal 3: Start the example application
-
Navigate to the specific example package you want to run:
cd examples/<package-name>
Replace
<package-name>
with the name of the example you want to run (e.g.,example-vite-react-sdk
). -
Install dependencies:
pnpm install
-
Start the development server:
pnpm run dev
After completing these steps, your example application should be running and connected to the local Dojo environment.
If you encounter issues on WSL:
-
Install the Dojo package:
npm i @dojoengine/create-dojo -g
-
Run the Dojo creation command:
npx @dojoengine/create-dojo
- Fork the repository and create your branch from
main
. - Make your changes and ensure they follow the project's coding style.
- Write tests for your changes if applicable.
- Run the test suite to ensure all tests pass.
- Submit a pull request with a clear description of your changes.
For more detailed information, please refer to our CONTRIBUTING.md file.