LLM Notice: This documentation site supports content negotiation for AI agents. Request any page with Accept: text/markdown or Accept: text/plain header to receive Markdown instead of HTML. Alternatively, append ?format=md to any URL. All markdown files are available at /md/ prefix paths. For all content in one file, visit /llms-full.txt
Skip to main content

Configuration

The flow.json file is the central configuration file for your Flow project. It tells the Flow CLI how to interact with networks, manage accounts, deploy contracts, and organize your project structure.

Quick Start​

When you run flow init, a basic flow.json file is created for you:


_15
{
_15
"networks": {
_15
"emulator": "127.0.0.1:3569",
_15
"mainnet": "access.mainnet.nodes.onflow.org:9000",
_15
"testnet": "access.devnet.nodes.onflow.org:9000"
_15
},
_15
"accounts": {
_15
"emulator-account": {
_15
"address": "f8d6e0586b0a20c7",
_15
"key": "ae1b44c0f5e8f6992ef2348898a35e50a8b0b9684000da8b1dade1b3bcd6ebee"
_15
}
_15
},
_15
"deployments": {},
_15
"contracts": {}
_15
}

This gives you everything you need to get started with local development. As your project grows, you'll add more configuration to support different networks and deployment targets.

Configuration Sections​

Networks​

The networks section defines which Flow networks your project can connect to.


_10
"networks": {
_10
"emulator": "127.0.0.1:3569",
_10
"mainnet": "access.mainnet.nodes.onflow.org:9000",
_10
"testnet": "access.devnet.nodes.onflow.org:9000"
_10
}

Common Networks:

  • emulator: Your local development environment.
  • testnet: Flow's test network for development and testing.
  • mainnet: Flow's production network.

Secure Connections: For enhanced security, you can specify network keys:


_10
"networks": {
_10
"testnetSecure": {
_10
"host": "access-001.devnet30.nodes.onflow.org:9001",
_10
"key": "ba69f7d2e82b9edf25b103c195cd371cf0cc047ef8884a9bbe331e62982d46daeebf836f7445a2ac16741013b192959d8ad26998aff12f2adc67a99e1eb2988d"
_10
}
_10
}

Accounts​

The accounts section defines the accounts you can use for transactions and deployments.

Simple account format​


_10
"accounts": {
_10
"my-account": {
_10
"address": "f8d6e0586b0a20c7",
_10
"key": "ae1b44c0f5e8f6992ef2348898a35e50a8b0b9684000da8b1dade1b3bcd6ebee"
_10
}
_10
}

Advanced account format​

For more control over key management:


_12
"accounts": {
_12
"my-account": {
_12
"address": "f8d6e0586b0a20c7",
_12
"key": {
_12
"type": "hex",
_12
"index": 0,
_12
"signatureAlgorithm": "ECDSA_P256",
_12
"hashAlgorithm": "SHA3_256",
_12
"privateKey": "ae1b44c0f5e8f6992ef2348898a35e50a8b0b9684000da8b1dade1b3bcd6ebee"
_12
}
_12
}
_12
}

Key Types:

  • hex: Standard hex-encoded private key.
  • file: Read key from a separate file.
  • bip44: Derive from mnemonic phrase.
  • google-kms: Use Google Cloud KMS.

File-Based Keys: For better security, you can store private keys in separate files:


_10
"accounts": {
_10
"admin-account": {
_10
"address": "f8d6e0586b0a20c7",
_10
"key": {
_10
"type": "file",
_10
"location": "./keys/admin.key"
_10
}
_10
}
_10
}

The key file should contain only the hex-encoded private key (for example, ae1b44c0f5e8f6992ef2348898a35e50a8b0b9684000da8b1dade1b3bcd6ebee).

Special Address Values:

  • "service": Use the default service account (emulator only)

Contracts​

The contracts section maps contract names to their source files.

Simple contract format​


_10
"contracts": {
_10
"MyContract": "./cadence/contracts/MyContract.cdc",
_10
"AnotherContract": "./cadence/contracts/AnotherContract.cdc"
_10
}

Advanced contract format with aliases​

Use aliases when contracts are already deployed on specific networks:


_10
"contracts": {
_10
"FungibleToken": {
_10
"source": "./cadence/contracts/FungibleToken.cdc",
_10
"aliases": {
_10
"testnet": "9a0766d93b6608b7",
_10
"mainnet": "f233dcee88fe0abe"
_10
}
_10
}
_10
}

When to Use Aliases:

  • For core contracts already deployed on mainnet or testnet.
  • To avoid dependency redeployment.
  • To use the official versions of common contracts.

Cadence import aliasing​

When you deploy 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.


_15
"contracts": {
_15
"FUSD": {
_15
"source": "./contracts/FUSD.cdc",
_15
"aliases": {
_15
"testnet": "0x9a0766d93b6608b7"
_15
}
_15
},
_15
"FUSD1": {
_15
"source": "./contracts/FUSD.cdc",
_15
"aliases": {
_15
"testnet": "0xe223d8a629e49c68"
_15
},
_15
"canonical": "FUSD"
_15
}
_15
}

Flow CLI automatically transforms imports for aliased contracts:


_10
import "FUSD"
_10
import "FUSD1"

Becomes:


_10
import FUSD from 0x9a0766d93b6608b7
_10
import FUSD as FUSD1 from 0xe223d8a629e49c68

Deployments​

The deployments section defines which contracts get deployed to which accounts on which networks.


_10
"deployments": {
_10
"emulator": {
_10
"emulator-account": ["MyContract", "AnotherContract"]
_10
},
_10
"testnet": {
_10
"my-testnet-account": ["MyContract"]
_10
}
_10
}

Format: "NETWORK": { "ACCOUNT": ["CONTRACT1", "CONTRACT2"] }

Important Notes:

  • Don't deploy contracts that have aliases defined for that network.
  • Contracts are deployed in dependency order automatically.
  • You can deploy the same contract to multiple accounts (but not in the same deploy command).

Emulators​

Customize emulator settings (optional):


_10
"emulators": {
_10
"custom-emulator": {
_10
"port": 3600,
_10
"serviceAccount": "emulator-account"
_10
}
_10
}

Complete example​

Here's a complete flow.json for a project with multiple contracts and networks:


_39
{
_39
"networks": {
_39
"emulator": "127.0.0.1:3569",
_39
"testnet": "access.devnet.nodes.onflow.org:9000",
_39
"mainnet": "access.mainnet.nodes.onflow.org:9000"
_39
},
_39
_39
"accounts": {
_39
"emulator-account": {
_39
"address": "f8d6e0586b0a20c7",
_39
"key": "ae1b44c0f5e8f6992ef2348898a35e50a8b0b9684000da8b1dade1b3bcd6ebee"
_39
},
_39
"testnet-account": {
_39
"address": "3ae53cb6e3f42a79",
_39
"key": "12332967fd2bd75234ae9037dd4694c1f00baad63a10c35172bf65fbb8ad1111"
_39
}
_39
},
_39
_39
"contracts": {
_39
"FungibleToken": {
_39
"source": "./cadence/contracts/FungibleToken.cdc",
_39
"aliases": {
_39
"testnet": "9a0766d93b6608b7",
_39
"mainnet": "f233dcee88fe0abe"
_39
}
_39
},
_39
"MyToken": "./cadence/contracts/MyToken.cdc",
_39
"MyNFT": "./cadence/contracts/MyNFT.cdc"
_39
},
_39
_39
"deployments": {
_39
"emulator": {
_39
"emulator-account": ["FungibleToken", "MyToken", "MyNFT"]
_39
},
_39
"testnet": {
_39
"testnet-account": ["MyToken", "MyNFT"]
_39
}
_39
}
_39
}

Manage configuration​

Rather than edit flow.json manually, use the CLI commands:


_11
# Add an account
_11
flow config add account
_11
_11
# Add a contract
_11
flow config add contract
_11
_11
# Add a deployment
_11
flow config add deployment
_11
_11
# Remove configuration
_11
flow config remove account my-account

Best Practices​

  1. Use CLI commands when possible instead of manual editing.
  2. Keep private keys secure - consider file-based keys for production.
  3. Use aliases for core contracts to avoid redeployment.
  4. Test on emulator first before you deploy to testnet.
  5. Use different accounts for different networks.
  6. Backup your configuration before you make major changes.
Rate this page