# Setup

Source: https://docs.interop.io/browser/developers/browser-platform/setup/index.html

## Overview

The purpose of the Main app is to handle complex and important operations, but its setup is extremely simple and easy. The following sections describe how to create a Main app for your **io.Connect Browser** project and install and initialize properly the respective libraries depending on the web framework you are using - JavaScript ( [`@interopio/browser-platform`](https://www.npmjs.com/package/@interopio/browser-platform)), React ([`@interopio/react-hooks`](https://www.npmjs.com/package/@interopio/react-hooks)), or Angular ([`@interopio/ng`](https://www.npmjs.com/package/@interopio/ng)). All libraries are free to install from the public NPM registry, but require a valid license to operate.

> ℹ️ *For information on purchasing the **io.Connect Browser** platform or requesting a trial license, [contact us](https://interop.io/contact/).*

## Initialization

### JavaScript

Install the [`@interopio/browser-platform`](https://www.npmjs.com/package/@interopio/browser-platform) library in your project:

```cmd
npm install @interopio/browser-platform
```

Import the package in your Main app and initialize the `@interopio/browser-platform` library using the `IOBrowserPlatform()` factory function. It's required to provide a valid license key in the [configuration](#configuration) object for the library:

```javascript
import IOBrowserPlatform from "@interopio/browser-platform";

// Configuration for initializing the library.
// The only required property is `licenseKey`.
const config = {
    licenseKey: "my-license-key"
};

// Use the `io` property of the object returned by
// the factory function to access the io.Connect APIs.
const { io } = await IOBrowserPlatform(config);
```

The factory function will initialize and configure everything needed for a fully functioning **io.Connect Browser** project.

### React

> ℹ️ *For more details on using the [`@interopio/react-hooks`](https://www.npmjs.com/package/@interopio/react-hooks) library, see the [Browser Client > React](https://docs.interop.io/browser/developers/browser-client/react/index.md) section.*

To install the `@interopio/react-hooks` library, execute the following command:

```cmd
npm install @interopio/react-hooks
```

For the library to operate properly in the Main app of an **io.Connect Browser** project, you must also install the following optional peer dependencies:

- The [`@interopio/browser`](https://www.npmjs.com/package/@interopio/browser) library.
- The React and ReactDOM libraries.

Initialize the `@interopio/react-hooks` library in one of the following ways. It's required to provide a valid license key in the [configuration](#configuration) object for the library:

- using the `<IOConnectProvider />` component:

```javascript
import { createRoot } from "react-dom/client";
import IOBrowserPlatform from "@interopio/browser-platform";
import { IOConnectProvider } from "@interopio/react-hooks";

// Settings for the internal initialization of the `@interopio/browser-platform` library.
const settings = {
    browserPlatform: {
        factory: IOBrowserPlatform,
        config: {
            licenseKey: "my-license-key"
        }
    }
};

const domElement = document.getElementById("root");
const root = createRoot(domElement);

root.render(
    // Wrap your root component in the `<IOConnectProvider />` component in order
    // to be able to access the io.Connect APIs from all child components.
    <IOConnectProvider fallback={<h2>Loading...</h2>} settings={settings}>
        <App />
    </IOConnectProvider>
);
```

-  using the `useIOConnectInit()` hook:

```javascript
import IOBrowserPlatform from "@interopio/browser-platform";
import { useIOConnectInit } from "@interopio/react-hooks";

const App = () => {
    const settings = {
        browserPlatform: {
            factory: IOBrowserPlatform,
            config: {
                licenseKey: "my-license-key"
            }
        }
    };

    const io = useIOConnectInit(settings);

    return io ? <Main io={io} /> : <Loader />;
};

export default App;
```

### Angular

> ℹ️ *For more details on using the [`@interopio/ng`](https://www.npmjs.com/package/@interopio/ng) library, see the [Browser Client > Angular](https://docs.interop.io/browser/developers/browser-client/react/index.md) section.*

The following table describes the Angular versions supported by the different major versions of the `@interopio/ng` library:

| Library Version | Supported Angular Versions |
|-----------------|----------------------------|
| `@interopio/ng` 6.0 | Supports Angular versions 19 and 20. Supports both standalone components and modules. Provides the `provideIoConnect()` function for configuring and initializing the `@interopio/ng` library in Angular apps that use standalone components. |
| `@interopio/ng` 5.0 | Supports all Angular versions up to and including 20. Supports both standalone components and modules. |

This package should be used only in Angular apps. If you have created your app with the Angular CLI, then you don't need to take any additional steps. Otherwise, make sure to install the Angular peer dependencies of `@interopio/ng` described in the `package.json` file of the library.

To install the `@interopio/ng` library, execute the following command:

```cmd
npm install @interopio/ng
```

For the library to operate properly in the Main app of an **io.Connect Browser** project, you must also install the following optional peer dependency:

- The [`@interopio/browser-platform`](https://www.npmjs.com/package/@interopio/browser-platform) library.

Initialize the `@interopio/ng` library in one of the following ways depending on whether you are using standalone components or modules. It's required to provide a valid license key in the [configuration](#configuration) object for the library.

#### Standalone Components

In `app.config.ts` of the Main app:

```typescript
import { ApplicationConfig } from "@angular/core";
import { provideIoConnect } from "@interopio/ng";
import IOBrowserPlatform, { IOConnectBrowserPlatform } from "@interopio/browser-platform";

// Main app configuration.
const config: IOConnectBrowserPlatform.Config = {
    licenseKey: "my-license-key"
};

export const appConfig: ApplicationConfig = {
    providers: [
        // Configuring and initializing the Main app.
        provideIoConnect({
            browserPlatform: {
                factory: IOBrowserPlatform,
                config
            }
        })
    ]
};
```

In `main.ts` of the Main app:

```typescript
import { bootstrapApplication } from "@angular/platform-browser";
import { appConfig } from "./app/app.config";
import { App } from "./app/app";

bootstrapApplication(App, appConfig);
```

#### Modules

The following example demonstrates initializing the `@interopio/ng` library in a Main app that use Angular versions 15 and later.

In `app.config.ts` of the Main app:

```typescript
import { ApplicationConfig, importProvidersFrom } from "@angular/core";
import { IOConnectNg } from "@interopio/ng";
import IOBrowserPlatform, { IOConnectBrowserPlatform } from "@interopio/browser-platform";

const config: IOConnectBrowserPlatform.Config = {
    licenseKey: "my-license-key"
};

export const appConfig: ApplicationConfig = {
    providers: [
        importProvidersFrom(
            IOConnectNg.forRoot({
                browserPlatform: {
                    factory: IOBrowserPlatform,
                    config
                }
            })
        )
    ]
};
```

The following example demonstrates initializing the `@interopio/ng` library in a Main app that use Angular versions 14 and older.

In `app.module.ts` of the Main app:

```typescript
import { NgModule } from "@angular/core";
import { AppComponent } from "./app.component";
import { IOConnectNg } from "@interopio/ng";
import IOBrowserPlatform, { IOConnectBrowserPlatform } from "@interopio/browser-platform";

const config: IOConnectBrowserPlatform.Config = {
    licenseKey: "my-license-key"
};

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        IOConnectNg.forRoot({
            browserPlatform: {
                factory: IOBrowserPlatform,
                config
            }
        })
    ],
    providers: [],
    bootstrap: [AppComponent]
});

export class AppModule { };
```

## Configuration

It's required to provide a valid license key in order to be able to initialize the Main app of your **io.Connect Browser** project.

You can also specify other optional settings for the io.Connect environment, APIs, libraries, and [Plugins](https://docs.interop.io/browser/capabilities/plugins/setup/index.md) by using the configuration object for initializing the [`@interopio/browser-platform`](https://www.npmjs.com/package/@interopio/browser-platform) library:

```javascript
import IOBrowserPlatform from "@interopio/browser-platform";
import IOWorkspaces from "@interopio/workspaces-api";

const config = {
    // Providing a valid license key.
    licenseKey: "my-license-key",
    browser: {
        // Enabling the Workspaces API.
        libraries: [IOWorkspaces]
    },
    workspaces: {
        // Specifying the location of the Workspaces App.
        src: "https://my-workspaces-app.com"
    },
    // Configuration for Global Layouts.
    layouts: {
        mode: "session"
    },
    // Configuration for connecting to io.Manager.
    manager: {
        url: "https://my-io-manager.com:4242/api",
        auth: {
            basic: {
                username: "username",
                password: "password"
            }
        },
        fetchIntervalMS: 10000,
        tokenRefreshIntervalMS: 15000,
        critical: true
    }
};

const { io } = await IOBrowserPlatform(config);
```

### Standard

The standard `Config` object for the [`@interopio/browser-platform`](https://www.npmjs.com/package/@interopio/browser-platform) library has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `applications` | `object` | Set a [local](https://docs.interop.io/browser/capabilities/app-management/index.md#app_definitions-local) or [remote](https://docs.interop.io/browser/capabilities/app-management/index.md#app_definitions-remote) source for app definitions. |
| `browser` | `object` | [`Config`](https://docs.interop.io/browser/reference/javascript/io.connect%20browser/config/index.md) object for the internal initialization of the [`@interopio/browser`](https://www.npmjs.com/package/@interopio/browser) library. This configuration will be used also if the Main app is registered as an io.Connect client in an **io.Connect Desktop** project. |
| `browserFactory` | `function` | The `@interopio/browser-platform` library will always initialize the latest version of the `@interopio/browser` library internally, but you can override this by passing your own io.Connect factory function. This is especially helpful if you want your Main app to run with a specific `@interopio/browser` library version and not the latest. |
| `channels` | `object` | Configure the [Channels](https://docs.interop.io/browser/capabilities/data-sharing/channels/index.md) that will be available in your project. |
| `clientOnly` | `boolean` | Set to `true` to initialize your Main app as a [Browser Client](https://docs.interop.io/browser/developers/browser-client/overview/index.md) app, skipping all Browser Platform related logic. Useful in certain cases during initialization when it isn't explicitly clear whether your app should be a Main app or a Browser Client. In such cases it's possible to acquire Browser Platform configuration or logic dynamically if your app is to be a Main app. |
| `connection` | `object` | Defines various [security connection settings](https://docs.interop.io/browser/getting-started/security/index.md#platform_settings-connection) as well as settings for [connecting to a local **io.Connect Desktop** instance](https://docs.interop.io/browser/capabilities/desktop/index.md). |
| `environment` | `object` | Object with custom data (excluding functions) that will be accessible via the `iobrowser` object injected in the global `window` object of the Main app and all Browser Client apps connected to it. |
| `gateway` | `object` | Configuration for the io.Connect Gateway. Includes settings for connecting to [**io.Bridge**](https://docs.interop.io/bridge/general-overview/index.md). For more details, see the [Capabilities > io.Bridge](https://docs.interop.io/browser/capabilities/bridge/index.md) section. |
| `intentResolver` | `object` | Configuration for the io.Connect [Intent Resolver](https://docs.interop.io/browser/capabilities/data-sharing/intents/overview/index.md#intent_resolver). *Available since **io.Connect Browser** 4.0.* |
| `layouts` | `object` | Configuration for [Global Layouts](https://docs.interop.io/browser/capabilities/windows/layouts/setup/index.md). |
| `licenseKey` | `string` | **Required.** Valid license key for enabling the **io.Connect Browser** platform. |
| `manager` | `object` | Configuration for connecting to [**io.Manager**](https://docs.interop.io/manager/overview/index.md). For more details, see the [Capabilities > io.Manager](https://docs.interop.io/browser/capabilities/manager/index.md) section. |
| `modals` | `object` | Configuration for the io.Connect [modal windows](https://docs.interop.io/browser/capabilities/windows/modals/setup/index.md). *Available since **io.Connect Browser** 4.0.* |
| `notifications` | `object` | Configuration for the **io.Connect Browser** [notifications](https://docs.interop.io/browser/capabilities/notifications/setup/index.md). |
| `otel` | `object` | Configuration for **io.Insights**. For more details, see the [Capabilities > io.Insights](https://docs.interop.io/browser/capabilities/insights/index.md) section. *Available since **io.Connect Browser** 3.4.* |
| `plugins` | `object` | Provide your custom logic which will be included in the boot sequence of the Main app. For more details, see the [Plugins](https://docs.interop.io/browser/capabilities/plugins/setup/index.md) section. |
| `serviceWorker` | `object` | Provide the Service Worker registered by your Main app. A Service Worker is necessary only if you want to use [Notifications](https://docs.interop.io/browser/capabilities/notifications/setup/index.md) with actions. |
| `themes` | `object` | Configuration for the io.Connect [Themes](https://docs.interop.io/browser/capabilities/windows/themes/index.md). |
| `type` | `"platform"` | This property isn't necessary when providing a standard `Config` object with platform configuration. If provided, must be set to `"platform"`. If missing, the platform will assume that this is a standard platform configuration (as opposed to a `RemoteConfigFromManager` object with settings for fetching the platform configuration from **io.Manager**). *Available since **io.Connect Browser** 4.3.* |
| `user` | `object` | Object describing the current platform user. It's highly recommended to set at least the `id` property of the `user` object as the [user details](#user_details) are consumed internally by the platform for caching and visualization purposes. |
| `widget` | `object` | Configuration for the io.Connect [widget](https://docs.interop.io/browser/capabilities/widget/index.md). *Available since **io.Connect Browser** 3.5.* |
| `windows` | `object` | Configuration for the [Window Management](https://docs.interop.io/browser/capabilities/windows/window-management/index.md) API. |
| `workspaces` | `object` | Configuration for the [Workspaces App](https://docs.interop.io/browser/capabilities/windows/workspaces/workspaces-app/index.md#workspaces_concepts-workspaces_app) and [Workspaces](https://docs.interop.io/browser/capabilities/windows/workspaces/overview/index.md). |

### io.Manager

Available since io.Connect Browser 4.3

Alternatively, the [`@interopio/browser-platform`](https://www.npmjs.com/package/@interopio/browser-platform) library factory function also accepts a `RemoteConfigFromManager` object instead of the standard `Config` object. The `RemoteConfigFromManager` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `enableCache` | `boolean` | If `true` (default), will enable persisting locally the platform configuration fetched from **io.Manager**. This can be useful if you want the platform to be able to initialize even in cases of connection interruptions. |
| `fetchTimeoutMs` | `number` | Interval in milliseconds to wait for fetch requests sent to **io.Manager** to complete. Defaults to `30000`. |
| `managerURL` | `string` | **Required.** URL pointing to the **io.Manager** REST API. |
| `modifyConfig` | `function` | Asynchronous or synchronous function that receives the configuration fetched from **io.Manager** as an argument. Use this function to modify the fetched configuration before initializing the platform. |
| `platformVersion` | `string` | Exact platform version for which to fetch configuration from **io.Manager**. Defaults to the current platform version. |
| `type` | `"manager"` | **Required.** Must be set to `"manager"` to indicate that the platform configuration will be fetched from **io.Manager**. |

## Remote Configuration

It's possible to provide configuration for your Main app from a remote source (e.g., by retrieving a custom configuration file from [**io.Manager**](https://docs.interop.io/manager/overview/index.md) or your own REST store).

### io.Manager

Available since io.Connect Browser 4.3

To instruct the platform to fetch its configuration directly from [**io.Manager**](https://docs.interop.io/manager/overview/index.md), pass a `RemoteConfigFromManager` object instead of the standard `Config` object when initializing the [`@interopio/browser-platform`](https://www.npmjs.com/package/@interopio/browser-platform) library. The `type` property of the `RemoteConfigFromManager` object must be set to `"manager"`:

```javascript
import IOBrowserPlatform from "@interopio/browser-platform";

const config = {
    // Must be set to `"manager"`.
    type: "manager",
    managerURL: "https://my-io-manager.com:4242/api",
    // Optional function for modifying the fetched configuration before the platform initializes.
    modifyConfig: (config) => {
        config.licenseKey = "my-license-key";

        return config;
    }
};

const { io } = await IOBrowserPlatform(config);
```

When caching is enabled (default), the platform will store the fetched configuration in `IndexedDB` and fall back to the cached version if the remote fetch fails. For more details about the available properties, see the `RemoteConfigFromManager` object in the [Configuration](#configuration) section.

### REST

To fetch the platform configuration from a custom REST store, you must implement your own logic for fetching the remote configuration file and passing it to your Main app. It's recommended to cache the configuration file so that it will be available and your Main app can be initialized even in cases of connection interruptions.

The following example demonstrates an opinionated approach for fetching a remote configuration file and initializing the Main app. The example uses Boolean flags stored in the remote configuration file that indicate which additional io.Connect libraries to initialize in the Main app. If this approach doesn't work for you, you should implement a different solution based on your specific use case:

```javascript
import IOBrowserPlatform, { IOConnectBrowserPlatform } from "@interopio/browser-platform";
import IOWorkspaces from "@interopio/workspaces-ui-react";

// Example REST store response structure.
interface ConfigPayload {
    // Standard configuration object for initializing the Main app. It's required to provide a valid license key.
    config: IOConnectBrowserPlatform.Config;
    // Optional object with Boolean flags indicating which additional io.Connect libraries to initialize.
    apis?: {
        workspaces?: boolean;
        modals?: boolean;
        search?: boolean;
    };
}

const start = async () => {
    // Fetching the remote configuration file for the Main app.
    const response = await fetch("https://my-rest-store");

    const configPayload: ConfigPayload = await response.json();

    // Extracting the standard configuration object for the Main app and the object with Boolean flags
    // indicating which additional io.Connect libraries to initialize.
    const { config, apis } = configPayload;

    // The `libraries` array will hold the factory functions for initializing the additional io.Connect libraries.
    const libraries = [];

    // The factory functions for initializing the additional io.Connect libraries can't be serialized as JSON.
    // To determine which libraries to initialize, use the Boolean flags stored in the `api` object of the
    // remote configuration file and push the respective factory function in the `libraries` array.
    if (apis?.workspaces) {
        libraries.push(IOWorkspaces);
    }

    // Ensuring that the `browser` property of the configuration object for the Main app exists
    // and that all its current settings will be preserved while also adding the `libraries` array.
    config.browser = { ...config.browser, libraries };

    const { io } = await IOBrowserPlatform(config);
};

start().catch(console.error);
```

## io.Connect Gateway

The `gateway` property of the configuration object for initializing the [`@interopio/browser-platform`](https://www.npmjs.com/package/@interopio/browser-platform) library allows you to configure the io.Connect Gateway, including settings for logging, client connections, authentication, and connecting to [**io.Bridge**](https://docs.interop.io/browser/capabilities/bridge/index.md).

The `gateway` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `authentication` | `object` | Settings for the io.Connect Gateway authentication. *Available since **io.Connect Browser** 4.3.* |
| `bridge` | `object` | Settings for [connecting to **io.Bridge**](https://docs.interop.io/browser/capabilities/bridge/index.md). If you provide settings for connecting to **io.Bridge**, you must also provide user details via the `user` property, otherwise the platform will throw an error and won't initialize. *Available since **io.Connect Browser** 4.2.* |
| `clients` | `object` | Settings for the io.Connect Gateway client connections. |
| `logging` | `object` | Settings for the io.Connect Gateway logging. |

The `authentication` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `usernameCaseSensitive` | `boolean` | If `true`, the username provided for authentication will be treated by the io.Connect Gateway as case-sensitive. Defaults to `false`. |

The `clients` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `buffer_size` | `number` | Size of the message buffer for client connections. |

The `logging` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `appender` | `function` | Function with the following signature: `(logInfo: LogInfo) => void`. Custom log appender for the io.Connect Gateway. |
| `level` | `"trace"` \| `"debug"` \| `"info"` \| `"warn"` \| `"error"` | Logging level for the io.Connect Gateway. |

## User Details

While the **io.Connect Browser** platform isn't meant to handle user authentication and while providing user details when initializing the platform is entirely optional, it's still highly recommended to do so.

User details can be used internally for separating the cache (app definitions, app preferences, Layouts) for different platform users on the same machine. For instance, providing any form of user ID will allow the platform to save default Global Layouts per user. If user details aren't provided (and the platform isn't connected to **io.Manager**, which handles user cache separation automatically), the default Global Layout will be saved as public for all users.

The details provided in the `user` object are also used in the [Profile panel](https://docs.interop.io/browser/capabilities/home-app/overview/index.md#using_the_home_app-profile_panel) of the Home App if you are building a platform by using the [`@interopio/home-ui-react`](https://www.npmjs.com/package/@interopio/home-ui-react) library.

The `user` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `email` | `string` | User email. |
| `firstName` | `string` | User first name. |
| `id` | `string` | **Required.** Unique ID for the user. |
| `lastName` | `string` | User last name. |
| `meta` | `any` | Any meta data associated with the user. |
| `role` | `string` | Role of the user. |
| `type` | `string` | Type of the user. |
| `username` | `string` | Username for the user. |

## io.Connect JavaScript Capabilities

Once the `@interopio/browser-platform` library has been initialized, your Main app has access to all io.Connect functionalities. For more detailed information on the different io.Connect capabilities and APIs, see the following sections:

- [Shared Contexts](https://docs.interop.io/browser/capabilities/data-sharing/shared-contexts/index.md)
- [Channels](https://docs.interop.io/browser/capabilities/data-sharing/channels/index.md)
- [Interop](https://docs.interop.io/browser/capabilities/data-sharing/interop/index.md)
- [Intents](https://docs.interop.io/browser/capabilities/data-sharing/intents/intents-api/index.md)
- [Window Management](https://docs.interop.io/browser/capabilities/windows/window-management/index.md)
- [Workspaces](https://docs.interop.io/browser/capabilities/windows/workspaces/workspaces-api/index.md)
- [Layouts](https://docs.interop.io/browser/capabilities/windows/layouts/layouts-api/index.md)
- [Themes](https://docs.interop.io/browser/capabilities/windows/themes/index.md)
- [Modals](https://docs.interop.io/browser/capabilities/windows/modals/modals-api/index.md)
- [App Management](https://docs.interop.io/browser/capabilities/app-management/index.md)
- [App Preferences](https://docs.interop.io/browser/capabilities/app-preferences/index.md)
- [Plugins](https://docs.interop.io/browser/capabilities/plugins/setup/index.md)
- [Notifications](https://docs.interop.io/browser/capabilities/notifications/notifications-api/index.md)
- [Search](https://docs.interop.io/browser/capabilities/search/search-api/index.md)