Inter-app API

There are several ways to communicate between apps, and events is one of them. This API package uses events. The API is designed to be published to an npm registry. Right now it will be published to npmjs.com but will be published to a private registry when the pipeline is ready.

Configuration for coordinating the exposure and reference of remotes between apps are defined in the remote configuration files.

Auto-generated Documentation

Development

The API is built as an npm package and imported into both shell and remote apps. To test changes to API locally before publishing:

1. cd to app directory level in remote
2. Run npm run build --workspaces
3. cd to app directory level in app importing api
4. Run sudo npm link <path to api directory>
   • If serving app, may need to re-serve
5. Re-build api with each change but no need to re-link

Publishing

1. Update 'version' via the major-minor-patch pattern
2. cd to app directory level
3. Run npm publish --workspaces --access=public
   • If publishing to npmjs.com, may need an account, be added to the @orcsrvcs organization, and be logged in via npm login

Files

package.json

Replace <app-name> with the name of the app.

index.ts

Shouldn't need to be modified
The entrypoint for when this package is imported. Everything exported in this file is immediately accessible by the developer.

common

Shouldn't need to be modified
Consists of the main class to handle events and all interfaces required to inferface with it. In the future, this may be exported to its own npm package and imported.

app-config.ts

Configuration file to properly expose and reference remotes.

remotes

All remote specific configurations are located within this directory. Each remote should have its own directory.

remotes.ts

One stop shop for referencing all remotes. This is convenient in showing developers which remotes and events are available. When adding new remotes, they need to be added here.

event-schemas.ts

One stop shop for referencing all event interfaces.

remote-config.ts

Configuration file to properly expose and reference remotes, and showing which events are associated with each remote.

events

A remote can contain zero or more events. Each event should have its own file.

event

Everything specific to an event is defined in these files.

• event name
• restrictions on how an app can use an event
• event data structure
• handling differences in API versions between apps

When updating the data structure, the version handling methods must be updated to properly convert the new structure to older structures. If the new event can't possibly be converted to an older structure, then consider throwing an error or something appropriate.

There is currently nothing to notify the developer the version handler needs to be updated if the structure has changed and API version has been updated, so it's up to the developer to remember to do that. Hopefully something will be implemented in the future.

Handling Duplicate Remotes / Custom Elements

By default, multiple remotes of the same type will all receive the same events from the shell. To ensure events go to only a specific remote, 'multiple = true' or 'eventSuffix != null' must be passed into getShellApi(), then the eventSuffix retrieved from the API and passed to the remote. The eventSuffix must then be passed into getRemoteApi().

• Remotes can coordinate via URL
• Custom elements can coordinate via HTML attributes