Union

Union is a library that will help you build plugins, third party customizations and inject them into any application. It provides resources for both sides, you application and the plugins or third party applications, to communicate safely.

Want to be updated about this project changes? Just follow the CHANGELOG.

Install 📑

This module is published under NPM registry, so you can install using any Node.js package manager.

npm install @unio/union

Install from CDN

The bundles of this module are also available on JSDelivr and UNPKG CDNs.

<!-- Using bundle from JSDelivr -->
<script src="https://cdn.jsdelivr.net/npm/@unio/union"></script>

<!-- Or using bundle from UNPKG -->
<script src="https://unpkg.com/@unio/union"></script>

<script>
  /**
   * The bundle exposes @unio/union through `Union` object.
   */
  
  console.log(Union.app);
  // => Same app object from installation though npm.

  console.log(Union.plugin);
  // => Same plugin object from installation though npm.
</script>

Usage

@unio/union provides two kinds of resources:

1. Consume plugins from an app
2. Provide a plugin for an app

Consume plugins from an app

import { start, seek } from "@unio/union/app";

/**
 * You can use start to load many plugins inside your application.
 * Start function will resolve after plugins are loaded and then you can use seek to retrieve the elements.
 */
start({ plugins: ["https://some-plugin-url-here"] }).then(async () => {
  /**
   * After started, you can use seek to retrieve the elements from all plugins by some grouping key.
   */
  const currentPageKey = "login-page";
  const customElements = await seek(currentPageKey);
  // => [{ type: ElementType.Button, text: "Login with Google", href: "https://google.com" }]
});

Provide a plugin for an app

import { setup } from "@unio/union/plugin";
import { ElementType } from "@unio/union/enums";

/**
 * You can provide custom elements to be used inside another applications as well.
 * First you have to setup your plugin and wait until it resolves a gateway.
 */
setup().then(async (gateway) => {
  /**
   * Gateway is a gate to the application, providing methods to add elements by grouping keys.
   */
  const pageKey = "login-page";
  const elements = [{ type: ElementType.Button, text: "Login with Google", href: "https://google.com" }];
  
  gateway.addElements(pageKey, elements);
});

License

Released under MIT license.

Contact Us 📞

⬆ Back to Top