README.md

hadron-app-registry

Concepts

Important

Use a plugin instead of a regular component for self-contained parts of the application which may need to keep state beyond the raw React component's lifetime.

Compass uses a special form of React components referred to as Plugins, distinguished from regular components in that they:

• Maintain state that can persist beyond their React component's lifetime
• Use a custom dependency injection mechanism for consuming dependencies that are used when initializing the plugin state

These dependencies are generally referred to as Services. For example, logging or telemetry in Compass are generally consumed by plugins as a service.

Compass uses a concept of scopes called App Registries. Currently, there are two levels of nesting:

• The global app registry, global in the sense of being a per-browser-window singleton
• A local app registry, where "local" currently means scoped to a single tab (not a technical restriction, just a convention).

The lifetime of a plugin's state is not tied to the lifetime of their React component, but rather to the lifetime of the local app registry (or the global one, if there is none).

Tip

Most plugins in Compass use a Redux store to keep track of their state. Some legacy plugins may still use Reflux or a similar mechanism where the state is provided to the top-level component of the plugin as a plain object.

Other than tracking plugin lifetimes, app registries provide a communication channel between plugins by being event emitters. If possible, new code should avoid this communication channel, as it is untyped and the specific method of passing messages should be an implementation detail. Alternative methods of passing messages between plugins include using React contexts to provide an API that can be used by nested plugins, or if that is not possible, your plugin can expose methods that other plugins can then access. (WorkspacesServiceProvider is currently an example of this pattern.)

Usage

For details on the usage of individual components or functions, refer to doc comments in the package itself.

import {
  globalAppRegistry,
  AppRegistry,
  AppRegistryProvider,
  registerHadronPlugin,
} from 'hadron-app-registry';
import CompassLogging from '@mongodb-js/compass-logging';
import {
  LoggingProvider,
  loggingLocator,
} from '@mongodb-js/compass-logging/provider';

const PluginWithLogger = registerHadronPlugin(
  {
    name: 'LoggingPlugin',
    component: function () {
      return <>...</>;
    },
    activate(opts, { logging }) {
      logging.log('Plugin activated!');
    },
  },
  { logging: loggingLocator }
);

ReactDOM.render(
  <AppRegistryProvider>
    <LoggingProvider>
      <PluginWithLogger />
    </LoggingProvider>
  </AppRegistryProvider>
);

Writing a service

Services are consumed by plugins through service locators, which are functions that return the instance of the service that the plugin is intended to use.

Typically, these functions are implemented using React contexts.

import { createServiceLocator } from 'hadron-app-registry';

const ConnectionStorageContext = createContext<ConnectionStorage | null>(null);

function useConnectionStorageContext(): ConnectionStorage {
  const connectionStorage = useContext(ConnectionStorageContext);
  if (!connectionStorage) {
    throw new Error('...');
  }
  return connectionStorage;
}

export const ConnectionStorageProvider = ConnectionStorageContext.Provider;
export const connectionStorageLocator = createServiceLocator(
  useConnectionStorageContext,
  'connectionStorageLocator'
);

Tip

If you need to use a service locator from inside a provider component, for example because your service depends on another service, you can use the createServiceProvider() method to achieve this. Otherwise, service locators can only be called by plugins during their initial activation.

Writing plugins

Plugins consist of:

• A name that identifies the plugin
• A top-level React component that serves as the plugin's React entry point
• An activate function that is called before the plugin is first rendered and which creates a (Redux) store for maintaining plugin state.

The activate function is expected to also return a cleanup function that is called when the lifetime of the plugin ends (i.e. the local app registry associated with it is destroyed). In order to make this easier, helpers are provided that automatically register cleanup functions:

const Plugin = registerHadronPlugin({
  name: 'TestPlugin',
  component: TestPluginComponent,
  activate(props, services, { on, addCleanup, cleanup }) {
    const store = configureStore();

    // Automatically removes event listeners when plugin is deactivated
    on(someEventEmitter, 'some-event', () => ...);
    addCleanup(() => { ... });

    return { store, deactivate: cleanup };
  }
}, { /* services */});

Note

The props and services parameters reflect the React properties passed to the plugin (Plugin in the example above) at the time of the first instantiation and the services returned by the service locators at that time; changes to the values returned from these will not have an effect on the already-instantiated plugin.

Testing support

For easier testing, plugins can be rendered with fixed services that are not looked up through the usual service locators. Additionally, the rendering of child plugins can be disabled, which can be used to speed up tests or avoid having to specify service dependencies for those child plugins.

import {
  render,
  cleanup,
  screen,
  waitFor,
} from '@mongodb-js/testing-library-compass';

const PluginWithMockServices = WorkspacesPlugin.withMockServices(
  {
    dataService: sinon.stub(),
  },
  { disableChildPluginRendering: true }
);

return render(<PluginWithMockServices />);