# @onflow/config

> Config for FCL-JS

Latest version **1.11.1** (published 2025-12-12) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @onflow/config
pnpm add @onflow/config
yarn add @onflow/config
bun add @onflow/config
```

## Health

**Score 70/100 (B)** — status: stable.

Positive: has types; esm support; no vulnerabilities; has provenance; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.11.1 |
| Published | 2025-12-12 |
| First published | 2020-07-17 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 206.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 333 |
| Author | Flow Foundation |
| Maintainers | han210, dapperj, dapper_labs, jeffreydoyle, harry.eth, chasefleming, gregorggg, turbolent_ff, jribbink, bthaile, nialexsan, sisyphussmiling, kan-flow-foundation, manny.ff, michael_flow, lmcmze |

## Links

- npm: https://www.npmjs.com/package/@onflow/config
- Repository: https://github.com/onflow/fcl-js
- Homepage: https://flow.com
- Issues: https://github.com/onflow/fcl-js/issues
- npm.io page: https://npm.io/package/@onflow/config

## Dependencies (4)

- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.25.7
- [@onflow/util-actor](https://npm.io/package/@onflow/util-actor.md) 1.3.5
- [@onflow/util-logger](https://npm.io/package/@onflow/util-logger.md) 1.3.4
- [@onflow/util-invariant](https://npm.io/package/@onflow/util-invariant.md) 1.2.5

## Recent versions

- 1.11.1 (latest) — 2025-12-12
- 1.6.0-alpha.0 (alpha) — 2025-07-24
- 1.2.2-event-streaming.1 (event-streaming) — 2023-11-29
- 1.2.0-typescript.0 (typescript) — 2023-11-01
- 1.11.0 — 2025-12-12
- 1.10.0 — 2025-12-12
- 1.6.3 — 2025-11-17
- 1.6.2 — 2025-11-06
- 1.6.1 — 2025-09-08
- 1.6.0 — 2025-07-25
- 1.5.2 — 2025-04-24
- 1.5.1 — 2024-11-27
- 1.5.1-alpha.0 — 2024-10-22
- 1.5.0 — 2024-09-28
- 1.5.0-alpha.0 — 2024-09-27
- … 37 more at https://npm.io/package/@onflow/config/versions

## README

# @onflow/config

Reactive configuration for Flow JS SDK and FCL

## Installation

```bash
npm install @onflow/config
```

## Usage

```javascript
import {config} from "@onflow/sdk"

// Reactively subscribe to config changes
config().subscribe(configData => console.log("CONFIG", configData))

// Set a config value
config().put("foo", "bar")

// .put can be chained
config()
  .put("foo", "bar")
  .put("baz", "rawr")

// Get a config value (it's async)
var configValue = await config().get("woot")
console.log(configValue) // undefined

// A fallback can be supplied for .get
var configValue = await config().get("woot", "fallback")
console.log(configValue) // "fallback"

config.put("woot", "woot")
var configValue = await config().get("woot", "fallback")
console.log(configValue) // "woot"

// Update a config value
config().put("count", 1)
var count = await config().get("count", 0)
console.log(count) // 1

config().update("count", oldValue => oldValue + 1)
var count = await config().get("count", 0)
console.log(count) // 2

// Delete a config value
config().delete("woot")
var configValue = await config().get("woot", "fallback")
console.log(configValue) // "fallback"

// Configs that match a pattern
config()
  .put("scope.A", 1)
  .put("scope.B", 1)

var scopeValues = await config().where(/^scope\.\s+/)
console.log(scopeValues) // { "scope.A": 1, "scope.B": 2 }
```

## Loading flow.json

Before loading a `flow.json`, you must set the network:

```javascript
import { config } from "@onflow/config"

// Set network (required before loading flow.json)
config().put("flow.network", "testnet")

// Load flow.json
await config().load({ flowJSON: require('./flow.json') })
```

## Import Aliases

Import aliases allow you to deploy the same contract to multiple addresses with different names, enabling version management and multi-instance deployments.

### flow.json Configuration

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

### How It Works

When `config.load(flowJSON)` is called:

1. **Contract addresses are extracted** based on the current network
2. **Canonical references are extracted** from the `canonical` field
3. **Values are stored in config**:
   ```typescript
   system.contracts.FUSD = "0x9a0766d93b6608b7"
   system.contracts.FUSD1 = "0xe223d8a629e49c68"
   system.contracts.FUSD1.canonical = "FUSD"
   ```

### Import Resolution

When resolving Cadence imports:

- `import "FUSD"` → `import FUSD from 0x9a0766d93b6608b7` (no canonical)
- `import "FUSD1"` → `import FUSD as FUSD1 from 0xe223d8a629e49c68` (with canonical)

The `canonical` field tells the resolver that `FUSD1` is an alias of the `FUSD` contract, so it generates the `import X as Y` syntax.

### Use Cases

**Multiple Versions:**
```json
{
  "contracts": {
    "FungibleToken": {
      "source": "./contracts/FungibleToken.cdc",
      "aliases": { "testnet": "0xf233dcee88fe0abe" }
    },
    "FungibleTokenV2": {
      "source": "./contracts/FungibleToken.cdc",
      "aliases": { "testnet": "0x9a0766d93b6608b7" },
      "canonical": "FungibleToken"
    }
  }
}
```

**Multiple Instances:**
```json
{
  "contracts": {
    "Token1": {
      "source": "./contracts/Token.cdc",
      "aliases": { "testnet": "0x1111" },
      "canonical": "Token"
    },
    "Token2": {
      "source": "./contracts/Token.cdc",
      "aliases": { "testnet": "0x2222" },
      "canonical": "Token"
    }
  }
}
```

### Dependencies

The `canonical` field also works with dependencies:

```json
{
  "dependencies": {
    "FungibleTokenV2": {
      "source": "mainnet://f233dcee88fe0abe.FungibleToken",
      "hash": "abc123...",
      "aliases": {
        "testnet": "0xf233dcee88fe0abe"
      },
      "canonical": "FungibleToken"
    }
  }
}
```

## Known Configuration Values

### Access Node

- `accessNode.api` _(default: emulator url)_ -- Where FCL will communicate with the Flow blockchain.
- `accessNode.key` _(default: null)_ -- Some Access Nodes require an API key.

```javascript
import {config} from "@onflow/fcl"

if (process.env.NODE_ENV === "production") {
  config()
    .put("accessNode.api", process.env.ACCESS_NODE_API)
    .put("accessNode.key", process.env.ACCESS_NODE_KEY)
}
```

### Decode

`decoder.*` -- Custom decoders for parsing JSON-CDC

```javascript
import {config, query} from "@onflow/fcl"

function Woot({x, y}) {
  this.x = x
  this.y = y
}

config()
  .put("decoder.Woot", woot => new Woot(woot))

var data = await fcl.query({
  cadence: `
    pub struct Woot {
      pub var x: Int
      pub var y: Int

      init(x: Int, y: Int) {
        self.x = x
        self.y = y
      }
    }

    pub fun main(): [Woot] {
      return [Woot(x: 1, y: 2), Woot(x: 3, y: 4), Woot(x: 5, y: 6)]
    }
  `
})

console.log(data) // [ Woot{x:1, y:2}, Woot{x:3, y:4}, Woot{x:5, y:6} ]
```

### Wallets

`wallet.discovery` _(default: FCL wallet discovery service url)_ -- Where FCL will attempt to authenticate

```javascript
import {config} from "@onflow/fcl"

if (process.env.NODE_ENV === "development") {
  // Use dev wallet during development
  config()
    .put("discovery.wallet", "http://localhost:8701/flow/authenticate")
}
```

## API Reference

### `config()`

Returns the config instance.

### `config().put(key, value)`

Sets a configuration value. Can be chained.

### `config().get(key, fallback?)`

Gets a configuration value, optionally with a fallback. Returns a Promise.

### `config().update(key, updateFn)`

Updates a configuration value using a function that receives the old value.

### `config().load({ flowJSON })`

Loads contract addresses and canonical references from a flow.json file.

**Parameters:**
- `flowJSON`: Flow JSON object or array of Flow JSON objects

**Requirements:**
- `flow.network` must be set before calling `load()`

### `config().delete(key)`

Deletes a configuration value.

### `config().all()`

Returns all configuration values as an object.

### `config().where(pattern)`

Returns configuration values matching a regex pattern.

### `config().subscribe(callback)`

Subscribes to configuration changes. Returns an unsubscribe function.

## See Also

- [Flow CLI Documentation](https://developers.flow.com/tools/flow-cli)
- [Flow JavaScript SDK](https://developers.flow.com/tools/fcl-js)
- [flow.json Configuration](https://developers.flow.com/tools/flow-cli/flow.json)

---
_Source: https://npm.io/package/@onflow/config · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._