# Networks

URL: https://docs.blux.cc/configuration/networks

Configure which Stellar networks your app supports.

The `networks` option defines which Stellar networks your app supports. If a connected wallet is on a network not in this list, Blux will prompt the user to switch.

`networks`, `defaultNetwork`, and `appName` are optional. The only required config field is `appId`, from [dashboard.blux.cc](https://dashboard.blux.cc).

## Defaults

| What you pass | What Blux uses |
|---|---|
| Neither `networks` nor `defaultNetwork` | **Mainnet** only (`networks.mainnet`) |
| `defaultNetwork` only | That network, as the only supported network |
| `networks` only | The list you passed, starting on the first item |
| Both | The list you passed, starting on `defaultNetwork` |
| No `appName`, or a blank one | `"App"` |

A config with only an App ID runs on Mainnet and shows up as `"App"` in wallet prompts:

<Tabs items={['React', 'Vanilla JS']} defaultIndex={0}>
<Tab value="React">
```tsx
<BluxProvider
  config={{
    appId: "your-app-id",
  }}
>
  {children}
</BluxProvider>
```
</Tab>
<Tab value="Vanilla JS">
```ts

createConfig({
  appId: "your-app-id",
});
```
</Tab>
</Tabs>

## Available Networks
```ts

// core.networks exposes:
{
  mainnet:    'Public Global Stellar Network ; September 2015',
  testnet:    'Test SDF Network ; September 2015',
  sandbox:    'Local Sandbox Stellar Network ; September 2022',
  futurenet:  'Test SDF Future Network ; October 2022',
  standalone: 'Standalone Network ; February 2017',
}
```

## Usage

<Tabs items={['React', 'Vanilla JS']} defaultIndex={0}>
<Tab value="React">
```tsx
<BluxProvider
  config={{
    appId: "your-app-id",
    networks: [networks.mainnet, networks.testnet],
    defaultNetwork: networks.mainnet,
  }}
>
  {children}
</BluxProvider>
```
</Tab>
<Tab value="Vanilla JS">
```ts

createConfig({
  appId: "your-app-id",
  networks: [core.networks.mainnet, core.networks.testnet],
  defaultNetwork: core.networks.mainnet,
});
```
</Tab>
</Tabs>

Pass `networks` when the app should support more than the default Mainnet. If that array is the only network option you set, Blux starts on the first item. You can change the active network later using `switchNetwork()`. The target has to be one of the networks in your config — when you omitted `networks`, that list is Mainnet only.

<Callout type="info">
  Network switching prompts only appear for wallets that support `getNetwork()`, such as Rabet and Freighter. You can disable this behavior entirely by setting `promptOnWrongNetwork: false` in your config.
</Callout>

## Custom Networks

If you need a network not in the built-in list, define it as a string and pass it to the `networks` array:
```ts
const customNetwork = "Standalone Network ; February 2020";

createConfig({
  appId: "your-app-id",
  networks: [customNetwork],
});
```

Make sure to also define a transport for any custom network. See the Transports page for details.

## Auto Sync

Blux periodically checks the connected wallet's active network. By default, it keeps the app's network in sync with the wallet — as long as the wallet's network is one of the supported networks in your config.

If your app calls `switchNetwork()` directly, Blux treats that as an app-controlled override and disables automatic syncing from that point on to prevent conflicts.

### Example

Given this config:
```ts
{
  networks: [networks.testnet, networks.futurenet],
}
```

| Step | Event | Result |
|------|-------|--------|
| 1 | Alice connects Freighter on **Mainnet** | Mainnet is unsupported → Wrong Network modal shown, app stays on **Testnet** |
| 2 | Alice switches Freighter to **Futurenet** | Supported → modal closes, app switches to **Futurenet** |
| 3 | Alice switches Freighter to **Testnet** | Supported → app auto-syncs to **Testnet** |
| 4 | App calls `switchNetwork(futurenet)` | App moves to **Futurenet**, auto-sync is now disabled |
| 5 | Alice toggles between Testnet/Futurenet | Wallet changes, app stays on **Futurenet** |
| 6 | Alice switches to **Mainnet** | Unsupported → Wrong Network modal, app stays on **Futurenet** |
| 7 | Alice switches back to **Testnet** | Modal dismissed, but app still stays on **Futurenet** (auto-sync still off) |