Component SDK - Getting Started

Download the SDK

The latest version of the SDK can be downloaded here.

Developer setup

Dependencies

Before using the SDK you should have the following software installed and available on your machine:

• Node.js LTS (v18)
• Yarn Classic
• Git

The SDK then makes several common libraries available in the global scope so that developers can keep their plugins nice and light. These dependencies are already marked as available at runtime in the build configurations provided in the sample project.

These are:

• The UX Framework (Mystique) tools
• React and React-DOM
• Material UI

Creating a plugin

The Component SDK provides a standard React / Typescript project that can be extended to develop new components.

• Download the latest version of the Component SDK
• Extract the zip to a folder.
  By default, the folder is called "omx-component-sdk".
  Rename this to a suitable project name. For example: 

  `mystique-plugin-acme`

• Open a terminal or command line and change directory into your new plugin.
• Initialize version control with git: 

  `$ git init`

• Install the dependencies: 

  `$ yarn install`

  
  This will install all the required dependencies, including webpack.
  It may take a few minutes to complete the installation.
• Start the project server: 

  `$ yarn start`

• Next, include the plugin in your web app manifest document.
  This will make any components built in your plugin available to include on pages.

1{
2   "plugins":[{ "src": "http://localhost:3001/bundle.js" }],
3   "routes": [
4     { "path":"hello", "component":"fc.hello" }
5   ]
6}

Plugin versioning

There are two options when adding a plugin to your manifest. You can:

• reference a file directly (e.g. 

  `{ "src": "http://myhost.com/myplugin/bundle.js" }`

  )
• reference a folder (e.g. 

  `{ "src": "http://myhost.com/myplugin/" }`

  )

In the folder case the framework will first check for a 

`version.json`

The 

`version.json`

`v`

`http://myhost.com/myplugin/version.json?v=1628209170000`

1{
2  "bundle": "bundle.8d2c4b9aebdc9b502b32.js"
3}

Where the hash value would come from a Webpack 

`contenthash`

This gives SDK developers the ability to:

• control when a new JS bundle is loaded by clients
• quickly roll back in response to any high-severity support tickets
• most importantly - cache heavy SDK plugins for a long period of time to limit performance impacts.

`v`

External dependencies

While most Javascript libraries should be usable in plugins, there are some best practice guidelines to keep in mind.

Prefer React-based

The UX Framework (aka Mystique) is based on ReactJS, so always prefer React-based libraries when possible.

Prefer Material UI

The standard library of Fluent components are all based on the Material UI framework.

Unit testing

Mocking hooks

Any Fluent hooks used in a component should generally be mocked in corresponding unit tests.

This can be done by: 1. importing with a wildcard at the module level 1. using 

`Jest.spyOn`

For example, a simple version of mocking the 

`useI18n()`

1import * as UseI18n from 'mystique/hooks/useI18n';
2
3const i18nValues: any = {
4    'fc.test.a': 'Test Value 1',
5};
6
7describe('Tests that require translation of strings', () => {
8
9    beforeEach(() => {
10        jest.spyOn(UseI18n, 'useI18n').mockImplementation(() => ({
11            translate: (key: string) => i18nValues[key]
12        }));
13    });
14
15    // tests go here...
16});

Consult the hook interface documentation in the 

`@types`