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 (e.g., 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/testnet
  • To avoid redeploying dependencies
  • To use the official versions of common contracts

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
}

Managing Configuration​

Instead of editing 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 using file-based keys for production
  3. Use aliases for core contracts to avoid redeployment
  4. Test on emulator first before deploying to testnet
  5. Use different accounts for different networks
  6. Backup your configuration before making major changes
Rate this page