Skip to main content
Version: 2.x

Migrating from V1

This doc guides you through migrating an existing micro-lc 1 application to micro-lc 2. We try to make this as easy as possible, and provide a migration CLI.

Main differences​

micro-lc 1 was a React application built as a vertical micro-frontend orchestrator (i.e., each micro-frontend corresponded to a specific route), which leverages another React application (the element composer) to implement horizontal micro-frontend orchestration (i.e., page composition). Moreover, micro-lc 1 enforced a pre-defined and ever-present top-bar/sidebar navigation layout.

micro-lc 2, rebuilt from the ground up, is a web component that includes both vertical and horizontal with a much lower footprint in terms of bundle size and loading speed. Moreover, micro-lc 2 leaves complete flexibility when it comes to building layouts, and implements some really useful features like internal communication and dependencies sharing.

Migration process​

To obtain a fully functional micro-lc 2 application, you firstly need to update micro-lc Docker image version. Remember that the container can now be tuned to cover some specific need.

Once the image has been updated, you need to adapt the configuration files to the new structure. Keep in mind that a CLI is provided to automate this migration, and that you can consult the new configuration JSON schema for reference.

tip

We provide a backend service to serve configurations with ACL and references resolution utilities.

micro-lc 1 needed two configuration files to define its registered micro-frontend, theming options, and layout preferences. In addition to them, it needed a configuration file for each plugin implementing the element composer for dynamic page composition.

authentication.json​

This file contained instructions on how to retrieve current user information and handle logout operations. This file is not needed in micro-lc 2 as its content can be moved in userMenu key of default layout configuration.

configuration.json​

This file contained the core configuration of the application, namely its plugins, theming, and addons. Its content can be transferred in micro-lc 2 configuration file. The main differences can be roughly outlined as:

  • micro-lc 1 plugins became application definitions and – possibly – layout menu items.
  • micro-lc 1 internal plugins became application definitions, but do not appear on the layout.
  • initial loading animation must be added on your index.html file.
  • micro-lc 1 right menu can be inserted in default layout slot.
  • micro-lc 1 theming configurations are spread in default layout properties.

Element composer configurations​

While you can still use the element composer registering it as a parcel (in which case configuration files stays the same), micro-lc 2 offers composition functionalities out of the box.

To use them, just register the applications as compose and tweak the configuration files accordingly. The main differences can be roughly outlined as:

  • custom elements sources are put together in sources properties.
  • micro-lc 1 busDiscriminator property is converted into a named eventBus.
  • micro-lc 1 rows and columns are converted into <div> with appropriate styling.
  • $ref property becomes definitions to align to JSON schema standard notation, and references in content changes from
    {
      "$ref": {
        "referencesString": "bar"
      },
      "foo": {
        "$ref": "referencesString"
      }
    }
    to
    {
      "definitions": {
        "referencesString": "bar"
      },
      "foo": {
        "$ref": "#/definitions/referencesString"
      }
    }

Automated migration​

The migration CLI can be used to automatically translate an application configurations from micro-lc 1 to micro-lc 2.

npx @micro-lc/middleware <args>

The CLI operates in two modes, config to translate old authentication.json and configuration.json files to the new configuration file, and compose to translate old element composer configuration files to new compose applications configurations.

The mode can be specified with flag -m (--mode) which can have value config (default) or compose.

Config Mode​

To invoke the CLI in this mode, it has to receive exactly two args, namely the absolute or relative path to authentication.json file followed by the absolute or relative path to configuration.json file.

npx @micro-lc/middleware --mode config <path_to_authentication.json_file> <configuration.json_file>

Available options are the following.

dir (-d)​

  • Type: string

Absolute or relative path of the output directory. The output file will be called config.json. If the specified directory does not exist, it will be created.

If no output dir is specified, the resulting file will be printed in standard output.

elementComposerUrlRegex (-e)​

  • Type: RegExp

This option can be used to identify micro-lc 1 plugins the uses the element composer and have to be converted in micro-lc 2 compose applications.

The regex specified with this option will be run against the pluginUrl of each plugin with integration mode qiankun. So, for example, if you have a plugin lke this:

{
  "id": "my-element-composer-plugin",
  "integrationMode": "qiankun",
  "pluginRoute": "/foo",
  "pluginUrl": "/element-composer/"
}

and you want it to be transformed in a compose application, the cli invocation would be

npx @micro-lc/middleware --m config -e "/element-composer/" <path_to_authentication.json_file> <configuration.json_file>

For compatibility reasons, the config URL of compose applications is set to /api/v1/microlc/configuration/${oldPlugin.props.configurationName}.json. After the conversion, remember to change it accordingly to your specific setup.

Compose Mode​

The CLI invoked in this mode can receive as many arguments as you want, each of them being a relative or absolute path (glob syntax can be used) resolving to one or more files to be converted.

npx @micro-lc/middleware --mode compose <paths_to_files...>

Available options are the following.

dir (-d)​

  • Type: string

Absolute or relative path of the output directory. The output files will be called as the respective input. If the specified directory does not exist, it will be created.

If no output dir is specified, the resulting files will be printed in standard output.