From c80a1551403f6eb365a111a58f34c2dc304e99a7 Mon Sep 17 00:00:00 2001
From: Chase Fleming <1666730+chasefleming@users.noreply.github.com>
Date: Thu, 20 Nov 2025 13:07:17 -0800
Subject: [PATCH] Add import aliasing docs

---
 .../tools/flow-cli/flow.json/configuration.md | 42 +++++++++++++++++--
 1 file changed, 39 insertions(+), 3 deletions(-)

diff --git a/docs/build/tools/flow-cli/flow.json/configuration.md b/docs/build/tools/flow-cli/flow.json/configuration.md
index b5eb1e85e2..4653c56175 100644
--- a/docs/build/tools/flow-cli/flow.json/configuration.md
+++ b/docs/build/tools/flow-cli/flow.json/configuration.md
@@ -155,6 +155,42 @@ Use aliases when contracts are already deployed on specific networks:
 - To avoid redeploying dependencies
 - To use the official versions of common contracts
 
+#### Cadence Import Aliasing
+
+When deploying the same contract to multiple addresses with different names, use the `canonical` field to reference the original contract. This allows you to import multiple instances of the same contract with different identifiers.
+
+```json
+"contracts": {
+  "FUSD": {
+    "source": "./contracts/FUSD.cdc",
+    "aliases": {
+      "testnet": "0x9a0766d93b6608b7"
+    }
+  },
+  "FUSD1": {
+    "source": "./contracts/FUSD.cdc",
+    "aliases": {
+      "testnet": "0xe223d8a629e49c68"
+    },
+    "canonical": "FUSD"
+  }
+}
+```
+
+Flow CLI automatically transforms imports for aliased contracts:
+
+```cadence
+import "FUSD"
+import "FUSD1"
+```
+
+Becomes:
+
+```cadence
+import FUSD from 0x9a0766d93b6608b7
+import FUSD as FUSD1 from 0xe223d8a629e49c68
+```
+
 ### Deployments
 
 The `deployments` section defines which contracts get deployed to which accounts on which networks.
@@ -201,7 +237,7 @@ Here's a complete `flow.json` for a project with multiple contracts and networks
     "testnet": "access.devnet.nodes.onflow.org:9000",
     "mainnet": "access.mainnet.nodes.onflow.org:9000"
   },
-  
+
   "accounts": {
     "emulator-account": {
       "address": "f8d6e0586b0a20c7",
@@ -212,7 +248,7 @@ Here's a complete `flow.json` for a project with multiple contracts and networks
       "key": "12332967fd2bd75234ae9037dd4694c1f00baad63a10c35172bf65fbb8ad1111"
     }
   },
-  
+
   "contracts": {
     "FungibleToken": {
       "source": "./cadence/contracts/FungibleToken.cdc",
@@ -224,7 +260,7 @@ Here's a complete `flow.json` for a project with multiple contracts and networks
     "MyToken": "./cadence/contracts/MyToken.cdc",
     "MyNFT": "./cadence/contracts/MyNFT.cdc"
   },
-  
+
   "deployments": {
     "emulator": {
       "emulator-account": ["FungibleToken", "MyToken", "MyNFT"]