Merge pull request #2854 from dfinity/dfx-json-info

Add page on `dfx.json` configuration details

docs/developer-docs/developer-tools/cli-tools/advanced-dfx/networks-json.mdx

@@ -108,7 +108,7 @@ Networks can also be defined in a project's `dfx.json` file. Only canisters with
 Network definitions in the `dfx.json` file can have the following configuration components:
 
 - `providers`: The network provider; can be `localhost` or any other domain name. Domain names must be a full URL, such as `https://domain.com`.
-- `type`: The type of network, either `ephemeral` or `persistent`. Ephmeral networks do not retain the same IDs for canisters, while persistent networks will retain the same canister IDs.
+- `type`: The type of network, either `ephemeral` or `persistent`. Ephemeral networks do not retain the same IDs for canisters, while persistent networks will retain the same canister IDs.
 
 To define a project-specific network, add a "networks" section to your `dfx.json` file such as:
 

docs/developer-docs/developer-tools/cli-tools/dfx-json.mdx

@@ -0,0 +1,193 @@
+---
+keywords: [reference, dfx, dfx.json schema]
+---
+
+import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
+
+# dfx.json configuration options
+
+<MarkdownChipRow labels={["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](/docs/current/developer-docs/developer-tools/cli-tools/dfx-json-reference).
+
+## 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:
+
+```json
+{
+  "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 IC 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:
+
+```json
+"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:
+
+```json
+  "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:
+
+```json
+{
+    "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:
+
+```json
+"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](/docs/current/developer-docs/developer-tools/cli-tools/advanced-dfx/networks-json).
+
+## Wasm optimization options
+
+Canisters can be optimized using [`wasm-opt`](https://github.com/WebAssembly/binaryen), which exposes a few different optimization options using the `optimize` configuration:
+
+
+```json
+{
+  "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`](https://github.com/WebAssembly/binaryen) documentation.
+
+## Further reading
+
+There are several workflow-specific `dfx.json` configuration options detailed in the full [`dfx.json` schema](/docs/current/developer-docs/developer-tools/cli-tools/dfx-json-reference).
+

sidebars.js

@@ -328,6 +328,7 @@ const sidebars = {
                 "developer-docs/developer-tools/cli-tools/cli-reference/dfx-upgrade",
                 "developer-docs/developer-tools/cli-tools/cli-reference/dfx-wallet",
                 "developer-docs/developer-tools/cli-tools/cli-reference/dfx-envars",
+                "developer-docs/developer-tools/cli-tools/dfx-json",
                 "developer-docs/developer-tools/cli-tools/dfx-json-reference",
                 {
                   type: "category",