# OpenFin Node.js adapter

Allows the use of the OpenFin API from node.js. Please note that the `launch` and `connect` methods are specific to a node environment.

## Prerequisites

-   Node.js 20 or greater

# Usage

## Connect

`connect` can be used to establish a connection to an OpenFin runtime from node.

A `uuid` value must be provided to identify the connection. Multiple connections require distinct `uuid` values.

A Runtime version or manifest URL must also be specified.

> Note: `connect` instantiates a Runtime instance if one does not exist for the given configuration. If a Runtime is already running, `connect` simply establishes a new connection.

### Connecting via Runtime Version

```javascript
import { connect } from '@openfin/node-adapter';

(async () => {
    const fin = await connect({
        uuid: 'my-uuid-123',
        runtime: {
            version: 'stable'
        }
    });
    await fin.Platform.startFromManifest('http://www.your-domain-goes-here.com/manifest.json');
})();
```

### Connecting via Manifest URL

```javascript
import { connect } from '@openfin/node-adapter';

(async () => {
    const fin = await connect({
        uuid: 'connection-id',
        manifestUrl: 'http://www.your-domain-goes-here.com/manifest'
    });
})();
```

---

## Launch

Unlike `connect`, `launch` starts an OpenFin application if not running and returns a port number instead of a `fin` object.

This port number can be provided to connect to create a `fin` object for the Runtime that has been created on the specific port.

`launch` can be called multiple times for a given application; however launches for an application that is already running result in a [run-requested](https://developer.openfin.co/docs/javascript/stable/interfaces/OpenFin.Events.ApplicationEvents.RunRequestedEvent.html) event being triggered instead of a relaunch. If the application is an OpenFin platform, this scenario results in the layout windows reloading.

### Launching and Connecting via Port

```javascript
import { launch, connect } from '@openfin/node-adapter';

(async () => {
    const port = await launch({
        manifestUrl: 'http://www.your-domain-goes-here.com/manifest'
    });

    const fin = await connect({
        address: `ws://localhost:${port}`,
        uuid: 'external-app-via-launch'
    });

    console.log(await fin.System.getRuntimeInfo());
})();
```

---

## Types

`@openfin/node-adapter` comes bundled with its own types.

If you wish to explicitly reference OpenFin types, the `OpenFin` namespace export can be used as follows:

### Type Usage Example

```typescript
import OpenFin, { connect } from '@openfin/node-adapter';

(async () => {
    const fin: OpenFin.Fin<'external connection'> = await connect({
        uuid: 'connection-id'
    });
    const platform: OpenFin.Platform = await fin.Platform.startFromManifest(
        'http://www.your-domain-goes-here.com/manifest'
    );
})();
```

---

# Migrating from openfin-adapter to @openfin/node-adapter

For users of the `connect` and `launch` functions in `openfin-adapter`, no changes are necessary, other than updating the dependency name.

If you are using the exported types from `openfin-adapter`, you can now use the `OpenFin` export that encapsualates them.

### Before

```typescript
import { launch, connect, Application, Fin } from 'openfin-adapter';

(async () => {
    const fin: Fin = await connect({
        uuid: 'external-connection-1',
        runtime: { version: 'stable' }
    });
    const app: Application = await fin.Application.start({...});
})()
```

### After

```typescript
import OpenFin, { launch, connect } from '@openfin/node-adapter';
(async () => {
    const fin: OpenFin.Fin<'external connection'> = await connect({
        uuid: 'external-connection-1',
        runtime: { version: 'stable' }
    });
    const app: OpenFin.Application = await fin.Application.start({...});
})()

```

---

## Further Reading

-   [Developer guide](https://developers.openfin.co/of-docs/docs/container-overview)
-   [API reference](https://developer.openfin.co/docs/javascript/stable)
