Browser Platform

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), React (@interopio/react-hooks), or Angular (@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.

JavaScript

Install the @interopio/browser-platform library in your project:

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 object for the library:

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 library, see the Browser Client > React section.

Install the @interopio/react-hooks library in your project:

npm install @interopio/react-hooks

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

• using the <IOConnectProvider /> component:

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:

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 library, see the Browser Client > Angular section.

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

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 peer dependencies of @interopio/ng described in the package.json file of the library.

Install the @interopio/ng library in your project:

npm install @interopio/ng

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 object for the library.

Standalone Components

In app.config.ts of the Main app:

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:

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:

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({
                browser: {
                    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:

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 { };

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 by using the configuration object for initializing the @interopio/browser-platform library:

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);

The configuration object for the @interopio/browser-platform library has the following properties:

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 or your own REST store).

To achieve this, 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:

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);

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 of the Home App if you are building a platform by using the @interopio/home-ui-react library.

The user object has the following properties:

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
• Channels
• Interop
• Intents
• Window Management
• Workspaces
• Layouts
• Themes
• Modals
• App Management
• App Preferences
• Plugins
• Notifications
• Search