dfx.json configuration options

Reference

Overview

Every project created and deployed with dfx requires a dfx.json file to be present in the project's root directory. The dfx.json file configures the project's settings such as the canisters in the project, their name, type, and source file, default project build settings, and other configuration parameters such as Wasm optimizations. This page will detail some of the most common configuration options. For a full list of the possible configuration settings in dfx.json, view the dfx.json schema.

Default `dfx.json` file

By default, when a project is created with dfx new <project-name>, and the options Motoko and No frontend canister are selected, the default dfx.json generated for the project will contain the following:

{
  "canisters": {
    "example_backend": {
      "main": "src/example_backend/main.mo",
      "type": "motoko"
    }
  },
  "defaults": {
    "build": {
      "args": "",
      "packtool": ""
    }
  },
  "output_env_file": ".env",
  "version": 1
}%

This configuration contains the following components:

canisters: Defines the canister names and settings for the project. In this default example, a single canister called example_backend is defined.
example_backend: Defines the name of the canister in this project.
main: The primary source code file for the canister that serves as the canister's entrypoint. By default, for Motoko canisters this file is main.mo. For Rust canisters,
type: Defines the type of the canister. Supported types are motoko, rust, assets, pull and custom. The Motoko and Rust languages are supported through the BIG SDK by default. custom type refers to canisters written in languages other than Motoko or Rust.
defaults: Default settings for the project's build.
build: Build process configuration.
args: Arguments for the packtool setting.
packtool: Configures a package management tool for your canister's dependencies. Examples include mops and vessel for Motoko.
output_env_file: Environment variables will be written to this file without overwriting any user-defined variables if the file already exists.
version: Refers to the iteration version for this dfx.json file. By default, versions of dfx.json start at version: 1.

Custom canister definitions

To define a canister to use a language other than Motoko or Rust, or to use a custom Wasm file, you can set the canister as "type": "custom" with the following additional arguments:

"canisters": {
"example_backend": {
    "build": "npx azle example_backend",
    "candid": "src/example_backend/example_backend.did",
    "gzip": true,
    "main": "src/example_backend/src/index.ts",
    "type": "custom",
    "wasm": ".azle/example_backend/example_backend.wasm"
}
}

build: The command that will build the canister.
candid: The file path to the canister's Candid interface definition file.
gzip: true or false if Wasm gzip should be used.
main: The primary source code file for the canister that serves as the canister's entrypoint.
type: Defines the canister as custom.
wasm: The file path to the canister's Wasm file.

Asset canisters

An asset canister is a type of canister that contains a project's frontend user interface and asset files. For projects created with dfx new <projectname> command with 'Vanilla JS' chosen as the frontend framework, the project's dfx.json file will contain the following asset canister definition:

  "canisters": {
    "example_frontend": {
      "dependencies": [
        "example_backend"
      ],
      "source": [
        "src/example_frontend/dist"
      ],
      "type": "assets",
      "workspace": "example_frontend"
    }
  },

dependencies: Defines what canister the asset canister is dependent on to communicate with.
source: The project directory containing the asset canister's source files.
type: Defines the canister as type assets.
workspace: The project directory containing this canister's package.json file.

Pullable canisters

Canisters that provide a public service at a static canister ID can be pulled into your project by defining "type": "pull". This indicates that the canister's Wasm and Candid file will be pulled from the specified canister ID on the mainnet.

Below is an example project that defines three canisters: dapp, which is dependent on dep_b and deb_c, both of which are pullable canisters:

{
    "canisters": {
        "dapp": {
            "type": "motoko",
            "main": "src/main.mo",
            "dependencies": [
                "dep_b", "dep_c"
            ]
        },
        "dep_b": {
            "type": "pull",
            "id": "yhgn4-myaaa-aaaaa-aabta-cai"
        },
        "dep_c": {
            "type": "pull",
            "id": "yahli-baaaa-aaaaa-aabtq-cai"
        }
    }
}

type: Defines the canister as type pull, meaning the canister's Wasm and Candid files will be retrieved from the mainnet.
id: Specifies the canister's ID on the mainnet that should be used to obtain the Wasm and Candid files.

Network settings

Local development network settings can be configured in dfx.json, such as:

"networks": {
    "dev": {
      "providers": [
        "https://ic0.app"
      ],
      "type": "persistent"
    }
  }

Network definitions can have the following configuration components:

providers: Defines the network provider, which can be localhost or any other domain name. Domain names must be a full URL, such as https://domain.com.
type: Defines the network type, which can be either ephemeral (do not retain same canister IDs) or persistent (retain the same canister IDs).

Learn more about custom network definitions and configurations.

Wasm optimization options

Canisters can be optimized using wasm-opt, which exposes a few different optimization options using the optimize configuration:

{
  "canisters": {
    "my_canister": {
      "optimize": "cycles"
    }
  }
}

optimize: Possible values are cycles and size. The value cycles optimizes your canister at a level 3 in wasm-opt, which is the recommended default value. size provides an aggressive optimization of the binary size. Learn more in the wasm-opt documentation.

dfx.json configuration options

Overview​

Default dfx.json file​

Custom canister definitions​

Asset canisters​

Pullable canisters​

Network settings​

Wasm optimization options​

Further reading​