Create a new codebase

  • Using the latest snapshot release:

    pnpm create mud@main <directory>
  • Using the latest pre-release:

    pnpm create mud@next <directory>

    Modify the codebase version

  • Switch to the latest snapshot release:

    pnpm mud set-version --tag main && pnpm install
  • Switch to the latest pre-release:

    pnpm mud set-version --tag next && pnpm install
  • Switch to a specific commit (opens in a new tab):

    pnpm mud set-version --commit <hash> && pnpm install


Onchain components

Foundry debugging

The MUD onchain components typically use the Foundry development stack (opens in a new tab), meaning any of Foundry's debugging tools are available. Use this prodecure to view the output from anvil (opens in a new tab):

  1. Add console.log to your systems, edit their Solidity files.

    • Import console.log.

      import { console } from "forge-std/console.sol";
    • Add console.log statements inside your Solidity functions.

      console.log("newValue:", newValue);
  2. Run anvil manually.

    anvil -b 1 --base-fee 0 | uniq | tee anvil.log

    Note that due to a bug, there might be multiple copies of the same console.log message. Piping through uniq (opens in a new tab) helps reduce this issue.

    You do not have to use tee anvil.log, but anvil logs so much that it is often useful to be able to look for information in the log file after it has scrolled off the screen.

  3. Edit packages/contracts/package.json to change the definition.

    "dev": "pnpm mud dev-contracts --rpc",

    Use, there is a weird bug that makes it a problem to use localhost is some circumstances.

  4. Run pnpm dev normally.

MUD dev tools

You can also see what is happening from your application by enabling to MUD dev tools. To do so, add this code to the client side of your application:

import { mount as mountDevTools } from "@latticexyz/dev-tools";
if (import.meta.env.DEV) {
  const { mount: mountDevTools } = await import("@latticexyz/dev-tools");
    config: mudConfig,
    publicClient: network.publicClient,
    walletClient: network.walletClient,
    latestBlock$: network.latestBlock$,
    blockStorageOperations$: network.blockStorageOperations$,
    worldAddress: network.worldContract.address,
    worldAbi: network.worldContract.abi,
    write$: network.write$,

In the minimal application you get from pnpm create mud@<version> <app>, the MUD dev tools are already included.

Server components

At present there is only one MUD server component, the Indexer. To produce debug outputs, specify the environment variable DEBUG before you start the indexer.

Information aboutDEBUG value
Synchronization with the onchain databasemud:store-sync:*
Requests for information from clientsmud:store-indexer