From 14cce7f8fb198f36ec305db9e9ef6158b7c80c80 Mon Sep 17 00:00:00 2001
From: Chase Fleming <chasefleming@users.noreply.github.com>
Date: Tue, 26 Nov 2024 13:19:30 -0800
Subject: [PATCH] Improve info and finding of info for FCL import syntax
 (#1014)

* Improve import syntax docs

* Add import syntax for FCL link

---------

Co-authored-by: Chase Fleming <1666730+chasefleming@users.noreply.github.com>
---
 docs/build/getting-started/fcl-quickstart.md |  8 +++
 docs/tools/clients/fcl-js/api.md             | 61 ++++++++++++++------
 2 files changed, 50 insertions(+), 19 deletions(-)

diff --git a/docs/build/getting-started/fcl-quickstart.md b/docs/build/getting-started/fcl-quickstart.md
index eb492da01c..1330c92ef9 100644
--- a/docs/build/getting-started/fcl-quickstart.md
+++ b/docs/build/getting-started/fcl-quickstart.md
@@ -226,6 +226,14 @@ In the above code:
 - If an error occurs during the query, we log it to the console.
 - We use the script from Step 2 to query the count from the `Counter` contract and format it using the `NumberFormatter` contract.
 
+:::info
+
+In this tutorial, we've shown you hardcoding addresses directly for simplicity and brevity. However, it's **recommended** to use the `import "ContractName"` syntax, as demonstrated in [Step 2: Local Development](./flow-cli.md). This approach is supported by the Flow Client Library (FCL) and allows you to use aliases for contract addresses in your `flow.json` file. It makes your code more flexible, maintainable, and easier to adapt across different environments (e.g., `testnet`, `mainnet`).
+
+Learn more about this best practice in the [FCL Documentation](../../tools/clients/fcl-js/api.md#using-flowjson-for-contract-imports).
+
+:::
+
 ### Step 2: Run the App
 
 Start your development server:
diff --git a/docs/tools/clients/fcl-js/api.md b/docs/tools/clients/fcl-js/api.md
index d7716fd7c0..ff63d5af1f 100644
--- a/docs/tools/clients/fcl-js/api.md
+++ b/docs/tools/clients/fcl-js/api.md
@@ -129,42 +129,65 @@ fcl
   .put('0xFlowToken', '0x7e60df042a9c0868');
 ```
 
-### Using Flow.json
+### Using `flow.json` for Contract Imports
 
-A simpler way to import contracts in scripts and transactions is to use the `config.load` method to ingest your contracts from your `flow.json` file. This keeps the import syntax unified across tools and lets FCL figure out which address to use for what network based on the network provided in config. To use `config.load` you must first import your `flow.json` file and then pass it to `config.load` as a parameter.
+A simpler and more flexible way to manage contract imports in scripts and transactions is by using the `config.load` method in FCL. This lets you load contract configurations from a `flow.json` file, keeping your import syntax clean and allowing FCL to pick the correct contract addresses based on the network you're using.
+
+### Setting Up
+
+#### 1. Define Your Contracts in `flow.json`
+
+Here’s an example of a `flow.json` file with aliases for multiple networks:
+
+```json
+{
+  "contracts": {
+    "HelloWorld": {
+      "source": "./cadence/contracts/HelloWorld.cdc",
+      "aliases": {
+        "testnet": "0x1cf0e2f2f715450",
+        "mainnet": "0xf8d6e0586b0a20c7"
+      }
+    }
+  }
+}
+```
+
+- **`source`**: Points to the contract file in your project.
+- **`aliases`**: Maps each network to the correct contract address.
+
+#### 2. Configure FCL
+
+Load the `flow.json` file and set up FCL to use it:
 
 ```javascript
 import { config } from '@onflow/fcl';
 import flowJSON from '../flow.json';
 
 config({
-  'flow.network': 'testnet',
-  'accessNode.api': 'https://rest-testnet.onflow.org',
-  'discovery.wallet': `https://fcl-discovery.onflow.org/testnet/authn`,
+  'flow.network': 'testnet', // Choose your network, e.g., testnet or mainnet
+  'accessNode.api': 'https://rest-testnet.onflow.org', // Access node for the network
+  'discovery.wallet': `https://fcl-discovery.onflow.org/testnet/authn`, // Wallet discovery
 }).load({ flowJSON });
 ```
 
-Let's say your `flow.json` file looks like this:
+With this setup, FCL will automatically use the correct contract address based on the selected network (e.g., `testnet` or `mainnet`).
 
-```
-{
-  "contracts": {
-		"HelloWorld": "cadence/contracts/HelloWorld.cdc"
-	}
-}
-```
+#### 3. Use Contract Names in Scripts and Transactions
 
-Then in your scripts and transactions, all you have to do is:
+After setting up `flow.json`, you can import contracts by name in your Cadence scripts or transactions:
 
-```
+```cadence
 import "HelloWorld"
-```
 
-FCL will automatically replace the contract name with the address for the network you are using.
+access(all) fun main(): String {
+    return HelloWorld.sayHello()
+}
+```
 
-> Note: never put private keys in your `flow.json`. You should use the [key/location syntax](../../../tools/flow-cli/flow.json/security.md) to separate your keys into a separate git ignored file.
+FCL replaces `"HelloWorld"` with the correct address from the `flow.json` configuration.
 
----
+> **Note**: Don’t store private keys in your `flow.json`. Instead, use the [key/location syntax](../../../tools/flow-cli/flow.json/security.md) to keep sensitive keys in a separate, `.gitignore`-protected file.
 
 ## Wallet Interactions