Modyo Docs

# Modyo CLI

The Modyo Command Line Interface (CLI) is a tool based on two fundamental principles: acceleration and integration. These principles are implemented through the get and push commands, respectively.

The main benefits of working with the Modyo CLI are:

  • Work locally: Allowing you to create widgets of any size or complexity.
  • Store widgets in local repositories: Making it easier to manage widgets and collaborate with other developers.
  • Create a widget once and reuse it on multiple sites

# Installation

To use the Modyo Command Line, you must first install it globally on your local machine. This will allow you to use the modyo-cli command, which allows you to initialize a project with some predefined front-end architectural decisions using the Modyo base template or with an experience from the Dynamic Framework catalog.

To use the Modyo CLI you can choose one of the following options:

  • Install modyo-cli globally for use from the terminal
$ npm i -g @modyo/cli #via npm
$ yarn global add @modyo/cli #via yarn
  • Run it without installation using npx
$ npx @modyo/cli #via npx
$ npx @modyo/cli@latest #via npx - pointing to a specific version

To verify that the installation was successful and confirm the installed version of the CLI, run this command:

$ modyo-cli version
@modyo/cli/3.3.0 darwin-arm64v8 node-v21.2.0

Tip

In some cases, it is necessary to reload the terminal profile or start a new session for the modyo-cli command to be available.

Modyo offers the ability to configure the auto-completion of CLI commands. For instructions on how to set it up, run one of the following commands:

$ modyo-cli autocomplete zsh
# o
$ modyo-cli autocomplete bash

# Initializing a new project

The fastest and easiest way to create your first micro-frontend is to use the React base template of our framework using the get command.

$ modyo-cli get dynamic-react-base-template my-project-name

This initializes a functional project to begin a new development.

Modyo also has a set of financial experience templates that further accelerate the development of solutions in the field of digital banking and the financial industry. You can find information about these experiences and how to obtain their templates in the Experiences section of the Dynamic Framework documentation.

Tip

All Dynamic Framework templates have a README file with information about their requirements and use.

An organization can also create its own templates to customize the initialization process. To get a customized template, use the organization option.

$ modyo-cli get --organization=myOrganization my-custom-template-repo my-project-name

From this point on, you already have a functional project, and you can get its dependencies and run the integrated server.

$ cd my-project-name
$ npm install
$ npm run start

In a web browser, visit http://localhost:8081/ (opens new window) to view the initialized project.

# Initial Setup

The next step is to configure your project to make it easier to load the microfrontend on Modyo platform and include it in the pages you build. You can specify everything as parameters in the push call, however, there is a .env file in which you can define a set of environment variables to specify all the attributes, such as the URL of the account, the site where it will be hosted and the access token, among others. For this configuration, you need to perform these actions beforehand:

  1. Get an access token to Modyo: To obtain the token you need to have a user or create one that has at least the site developer-cli role in the sites or stages where you will deploy your micro-frontend. Once you've created the user, you can set up an access token for it. You will use this access token to obtain the necessary information to configure and activate deployments on the platform.

  2. Identify the site or stage: Use the Modyo administrative API with the access token obtained previously, to obtain the information of the site or stage where the microfrontend will be deployed as well as the URL of the account, the host or ID of the site or the ID of any stage of the site. To do this, attach the Bearer type authorization header as follows:

$ curl https://my-org.modyo.cloud/api/admin/sites\?only\[\]\=id\&only\[\]\=host\&only\[\]\=stages -H 'Authorization: Bearer gT0ogW43lSy4nV9cYtc_hH0i_sUNq01q-12ptFzoW8'

The command returns a list with the information needed to configure your microfrontend in Modyo. It shows the sites, with their respective stages, to which the user has access. From this list you can get the id and the host you need to configure the deployment.

{
  "sites": [
    {
      "id": 1,
      "host": "my-Site",
      "stages": []
    },
    {
      "id": 2,
      "host": "portal",
      "stages": [
        {
          "id": 3,
          "uuid": "7a5d4b2d-de98-4c7f-8f0d-2c08599a218c",
          "name": "Portal",
          "host": "portal",
          "stage_name": "main",
          "created_at": "2019-03-15T11:02:07.000-03:00",
          "original_stage": "",
          "base_stage": true
        },
        {
          "id": 4,
          "uuid": "951b258b-5c86-4e7b-a21a-8e605e9cf0de",
          "name": "Portal Certification",
          "host": "cert-portal",
          "stage_name": "Cert",
          "created_at": "2022-08-10T18:03:19.000-04:00",
          "original_stage": "main",
          "base_stage": false
        }
      ]
    }
  ]
}
  1. Configure the .env file: Once you have obtained the list of sites and stages where you can identify the ID and the host, configure the .env file with the corresponding information. You can use the example file provided, called .env.example, that is included in the base template, which includes the necessary variables predefined and a brief description of each of them.
# Base URL base of the organization in Modyo
MODYO_ACCOUNT_URL=https://my-org.modyo.cloud/
# Where you will deploy your micro frontend, you can use either the host or the ID but not both.
# MODYO_SITE_HOST=my-site
MODYO_SITE_ID=1
# The token authorizing the deployment, taken from Modyo
MODYO_TOKEN=gT0ogW43lSy4nV9cYtc_hH0i_sUNq01q-12ptFzoW8
# The version of Modyo platform where the deployment will take place (8 or 9)
MODYO_VERSION=9
# The name of the directory that contains the micro frontend's bundle
MODYO_BUILD_DIRECTORY=build
# The name that will identify your Micro Frontend in Modyo
MODYO_WIDGET_NAME=my-project
# This directive is necessary to safely remove some libraries from the Liquid parser
MODYO_DISABLE_LIQUID_REGEX=raw
  • MODYO_ACCOUNT_URL The URL of the domain of our Modyo deployment.
  • MODYO_SITE_HOST The host of the site where you want to deploy the micro-frontend. It is not necessary if the site id is specified.
  • MODYO_SITE_ID The id of the site where you want to deploy the micro-frontend.
  • MODYO_TOKEN The user access token to be used for micro-frontend deployments.
  • MODYO_VERSION The version of Modyo. For older versions it is 8 and the current one is 9.
  • MODYO_BUILD_DIRECTORY The name of the folder containing the build result, such as “dist” or “build” depending on the framework used.
  • MODYO_WIDGET_NAME The name the widget will have after being deployed on the platform.
  • MODYO_DISABLE_LIQUID_REGEX Defines a regular expression for selecting files that need to disable the use of Liquid, for example, template files where the definition or use of variables is likely to collide with their use in Liquid.

# Deploy

Once your micro-frontend is configured and ready, you can build your widget.

This command will perform the necessary actions to prepare your microfrontend for production, cleaning and minifying the final files.

$ npm run build

To send it to Modyo, use the push command. This command uses your settings to select the site or stage and check if the microfrontend already exists in Modyo. Depending on the case, you will create or update it on the platform.

$ modyo-cli push

Activate the automatic publication of the microfrontend on the platform using the -p parameter.

$ modyo-cli push -p

Attention

The user who owns the token must have a site reviewer or admin role on the site where you are deploying the micro-frontend in order for the publication to be carried out correctly.

# Next steps

Once a widget is deployed and published in Modyo, it is available for use on the pages of the site to which it belongs.

If you have defined variables, their values can be specified globally or privately to each instance of the microfrontend. For more information on functionalities on Modyo sites, refer to the Channels documentation specifically the widget page and widgets sections

# Quick guide

The commands available in the Modyo CLI and the description of each of the options are:

  • modyo-cli (-v|--version|version) Prints the modyo-cli version.
$ modyo-cli (-v|--version|version)
@modyo/cli/3.3.0 darwin-arm64v8 node-v21.2.0
  • modyo-cli help Show contextual help for the specified command.
USAGE
  $ modyo-cli help [COMMAND]

ARGUMENTS
  autocomplete Display autocomplete installation instructions
  get          Pull a widget from our catalog into a new directory
  help         Display help for modyo-cli
  push         Push widget to Modyo platform
  • modyo-cli help autocomplete

Show autocomplete instructions, if the option is configured.

USAGE
  $ modyo-cli autocomplete [SHELL]

ARGUMENTS
  SHELL       shell type

OPTIONS
  -r, --refresh-cache   Refresh cache (ignores displaying instructions)

EXAMPLE
  $ modyo-cli autocomplete
  $ modyo-cli autocomplete bash
  $ modyo-cli autocomplete zsh
  $ modyo-cli autocomplete --refresh-cache
  • modyo-cli help get

The get command is used to get a widget template from our experience catalog using a token provided by Modyo.

USAGE
  $ modyo-cli get NAME [DIRECTORY]

ARGUMENTS
  NAME       The name of the widget
  DIRECTORY  Name of directory to init

OPTIONS
  -f, --force        Override folder if exist
  -h, --help         Output usage information
  -o, --organization [default: modyo] Github organization
  -x, --no-install   Don't install packages

EXAMPLE
  $ modyo-cli get name [directory]
  • modyo-cli help push

Integrate a widget written in Vue to the selected Site in Modyo Platform.

USAGE
  $ modyo-cli push NAME

ARGUMENTS
  NAME  The name of the widget

OPTIONS
  -b, --build-command=build-command      [default: build] Build command in package.json
  -d, --build-directory=build-directory  [default: dist] Build directory path
  -h, --help                             Output usage information
  -i, --site-id=site-id                  Id of the site where the widget will be pushed
  -l, --disable-liquid                   Disable Liquid
  -n, --site-host=site-host              Host of the site where the widget will be pushed
  -p, --publish                          Force widget publication
  -t, --token=token                      (required) Modyo Api token
  -u, --account-url=account-url          (required) URL of your Modyo account ex("https://account.modyo.com")
  -v, --version=8|9                      [default: 9] Version of Modyo platform

EXAMPLE
  $ modyo-cli push <NAME>
  • modyo-cli preview

The preview command allows you to preview a widget locally and view it styled for you site, before publishing it.

Requirements: To make use of the preview command, make sure you have:

  • A properly configured .env (opens new window) file. The MODYO_ACCOUNT_URL, MODYO_SITE_HOST or MODYO_SITE_ID, and MODYO_TOKEN fields are requisite.
  • A local server running with the widget you want to preview.

Once you have your .env file configured and your project running on the local server, follow these steps:

  1. Open a new terminal window.
  2. Run the modyo-cli preview command.

Important

To see a change, you must manually refresh your web app. Click refresh to load the changes.

Modyo uses default variables for widgets preview, you can modify them as needed. The predefined variables are:

  • MODYO_LOCAL_PORT: Local server port (default: 8080)
  • MODYO_LOCAL_DOM_ID: ID of the widget's container element (default: widgetName)
  • MODYO_LOCAL_ENTRY_JS: Main JavaScript file (default: main.js)

Also, you can select whether you want to preview your widget in the published version of your site or in the editable version. To do this, click on the box under templates. The text will change from published to editable.

These commands allow you to select the local entry points that you want to use.

OPTIONS

-p, –port=<value> [default: 8080) Deploy port local widget running
-s, –dom-id=<value> [default: widgetName] Container id of the widget
-j, –entry-js=<value> [default: main.js] Entry JS file of the widget

EXAMPLE

MODYO_LOCAL_PORT=8080
MODYO_LOCAL_DOM_ID=widgetName
MODYO_LOCAL_ENTRY_JS=main.js

# Code Splitting

Widgets allow you to develop micro frontends for your Modyo sites, thus increasing the functionality of your site.

However, by including external libraries or increasing the complexity of a widget, you can face excessive load times or exceed the size limits established for widgets in Modyo, negatively affecting the development experience and that of the user.

The code splitting technique allows you to divide your widgets' code into components that are loaded on demand or in parallel, solving these problems. The benefits of code splitting include:

  • Reduction in loading speed.
  • Improved interaction time.
  • Elimination of restrictions on the size of widgets.
  • Increased performance.

# CLI commands for code splitting

With Modyo's command line interface (CLI), you can publish and update a widget developed externally or in which you have implemented code splitting.

When you create a widget with Modyo CLI, your widget will have a label with the CLI text next to its name.

In the case of widgets created with code splitting, you must specify which is the main file and which chunks will be loaded dynamically, as required.

To package a file as a zip in Modyo CLI use these options:

  • zip: package the widget bundle to send it to the platform.
  • zip-entry-css: main CSS file of the widget.
  • zip-entry-js: main JS file of the widget.

Example:

modyo-cli push --zip --zip-entry-css=main.css --zip-entry-js=main.js

← Templates →