docs: migrating guide

Author: ilbertt

docs/src/content/docs/_sidebar.json

@@ -45,10 +45,20 @@
             }
           }
         ]
-      },
+      }
+    ]
+  },
+  {
+    "label": "Guides",
+    "collapsed": false,
+    "items": [
       {
         "label": "Bindings Structure",
         "link": "/structure"
+      },
+      {
+        "label": "Migrating",
+        "link": "/migrating"
       }
     ]
   },

docs/src/content/docs/migrating.md

@@ -0,0 +1,139 @@
+---
+title: Migrating
+prev: false
+next: false
+---
+
+This guide explains how to migrate your bindings generation from the previous tools like [dfx](https://internetcomputer.org/docs/building-apps/developer-tools/dfx/) or [didc](https://internetcomputer.org/docs/building-apps/interact-with-canisters/candid/candid-tools#didc) to `@icp-sdk/bindgen`.
+
+## From dfx (Rust canister)
+
+### Before
+
+If you were using `dfx` to generate bindings, your configuration was likely to be like this:
+
+```json title="dfx.json"
+{
+  "canisters": {
+    "hello-world-backend": {
+      "candid": "src/hello-world-backend/hello-world-backend.did",
+      "package": "hello-world-backend",
+      "type": "rust"
+    },
+    ...
+  }
+}
+```
+
+And you were generating bindings with the following command:
+
+```bash
+dfx generate
+```
+
+This was typically writing the bindings' files in the `src/declarations/hello-world-backend` directory, unless you configured the `canisters.hello-world-backend.declarations` field.
+
+### After
+
+Now, you can migrate to `@icp-sdk/bindgen` in [CLI mode](./cli) by running the following command (typically in a script in the `package.json` file of the frontend):
+
+```bash
+icp-bindgen --did-file ./src/hello-world-backend/hello-world-backend.did --out-dir ./src/hello-world-frontend/backend
+```
+
+> In case you configured the `canisters.hello-world-backend.declarations` field, you can pass the `canisters.hello-world-backend.declarations.output` value to the `--out-dir` flag. Note that in `@icp-sdk/bindgen`, there's no way to avoid generating the [TypeScript declarations](./structure#declarationsservice-namediddts).
+
+This will generate the bindings in the `src/hello-world-frontend/backend` directory. See the [Bindings Structure](./structure) page for more information on the generated files.
+
+> The same can be applied for a canister configured as `type: custom` in the `dfx.json` file.
+
+## From dfx (Motoko canister)
+
+### Before
+
+If you were using `dfx` to generate bindings, your configuration was likely to be like this:
+
+```json title="dfx.json"
+{
+  "canisters": {
+    "hello-world-backend": {
+      "main": "src/hello-world-backend/main.mo",
+      "type": "motoko"
+    },
+    ...
+  }
+}
+```
+
+And you were generating bindings with the following command:
+
+```bash
+dfx generate
+```
+
+This was typically writing the bindings' files in the `src/declarations/hello-world-backend` directory, unless you configured the `canisters.hello-world-backend.declarations` field.
+
+### After
+
+In Motoko, the Candid declaration file (`.did`) is generated by `dfx` at build time. It's typically written in the `.dfx/<network-name>/canisters/hello-world-backend/hello-world-backend.did` file.
+
+Now, you can migrate to `@icp-sdk/bindgen` in [CLI mode](./cli) by running the following commands (typically in a script in the `package.json` file of the frontend):
+
+```bash
+dfx build --check hello-world-backend # can be skipped if you already built the canister
+icp-bindgen --did-file ./.dfx/local/canisters/hello-world-backend/hello-world-backend.did --out-dir ./src/hello-world-frontend/backend
+```
+
+> In case you configured the `canisters.hello-world-backend.declarations` field, you can pass the `canisters.hello-world-backend.declarations.output` value to the `--out-dir` flag. Note that in `@icp-sdk/bindgen`, there's no way to avoid generating the [TypeScript declarations](./structure#declarationsservice-namediddts).
+
+This will generate the bindings in the `src/hello-world-frontend/backend` directory. See the [Bindings Structure](./structure) page for more information on the generated files.
+
+---
+
+For a more sophisticated approach, you can configure the `canisters.hello-world-backend.declarations` field to write the `.did` file to a directory of your choice and then use the `--did-file` flag to point to it. For example:
+
+```json title="dfx.json"
+{
+  "canisters": {
+    "hello-world-backend": {
+      "main": "src/hello-world-backend/main.mo",
+      "type": "motoko",
+      "declarations": {
+        "bindings": ["did"],
+        "output": "candid"
+      }
+    },
+    ...
+  }
+}
+```
+
+And then you can run the following commands:
+
+```bash
+dfx generate --check hello-world-backend
+icp-bindgen --did-file ./candid/hello-world-backend.did --out-dir ./src/hello-world-frontend/backend
+```
+
+## From didc
+
+### Before
+
+If you were using `didc` to generate bindings, you were likely running the following commands:
+
+```bash
+didc bind --target js ./service.did > ./service.did.js
+didc bind --target ts ./service.did > ./service.did.d.ts
+```
+
+### After
+
+Now, you can migrate to `@icp-sdk/bindgen` in [CLI mode](./cli) by running the following command:
+
+```bash
+icp-bindgen --did-file ./service.did --out-dir ./service
+```
+
+This will generate the bindings in the `service` directory. See the [Bindings Structure](./structure) page for more information on the generated files.
+
+> Note: There's no way to avoid generating the [TypeScript declarations](./structure#declarationsservice-namediddts).

docs/src/content/docs/structure.md

@@ -398,6 +398,8 @@ If provided, the `actorOptions` will be passed to the [`Actor.createActor`](http
 
 This folder contains the actual Candid JS bindings. It generates the same bindings that the [`dfx generate`](https://internetcomputer.org/docs/building-apps/developer-tools/dfx/dfx-generate) command was generating.
 
+See the [Migrating](./migrating) page for more information on how to migrate from `dfx generate`.
+
 ### `declarations/<service-name>.did.d.ts`
 
 This file is used in TypeScript projects to type the Candid JS bindings generated in [`declarations/<service-name>.did.js`](#declarationsservice-namedidjs).