Fluent Commerce Logo
Docs
Sign In

Component SDK - Getting Started

Essential knowledge

Author:

Fluent Commerce

Changed on:

8 July 2024

Overview

Getting Started Guide for Component SDK

Key points

  • Download the Component SDK
  • Developer setup requirement
  • Component SDK Unit testing example

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:

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:

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}

Language: json

Name: Sample Manifest using a custom Plugin

Description:

[Warning: empty required content area]

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`
 file at the root of the specified folder and take the bundle name from there.

The 

`version.json`
 is retrieved with a 
`v`
 parameter of the current date rounded to the nearest 10 seconds to avoid stale cache hits (e.g. 
`http://myhost.com/myplugin/version.json?v=1628209170000`
).

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

Language: json

Name: The structure of this file is simply:

Description:

[Warning: empty required content area]

Where the hash value would come from a Webpack 

`contenthash`
 (see Webpack Caching) or equivalent.

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.

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`
 to swap out the implementation with something that returns what your component is expecting

For example, a simple version of mocking the 

`useI18n()`
 hook might look like this:

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});

Language: typescript

Name: Example

Description:

[Warning: empty required content area]

Consult the hook interface documentation in the 

`@types`
 folder of your SDK project for more details on hook signatures and response types.

Fluent Commerce

Fluent Commerce

Copyright © 2024 Fluent Retail Pty Ltd (trading as Fluent Commerce). All rights reserved. No materials on this docs.fluentcommerce.com site may be used in any way and/or for any purpose without prior written authorisation from Fluent Commerce. Current customers and partners shall use these materials strictly in accordance with the terms and conditions of their written agreements with Fluent Commerce or its affiliates.

Fluent Logo