Upgrade CLI version

Upgrade to the latest CLI version

Updating from 1.x.x to CLI 2.x.x

You can update to the latest CLI version by running the global install command again:

npm install -g @interplay/cli @interplay/cli-plugin-react

Run the version command to check that you are now running the expected version:

interplay --version

Upgrading from CLI 1.x.x to 2.0.0

CLI version 1.0.19 is deprecated but currently still compatible with the Interplay API and you can continue using it to import your components. A number of CLI features such as presetRules, token import and deploy targets are only available using the 2.0.0 config format.

Changes to settings file structure

CLI 2.x.x is compatible with the 1.x.x configuration file structure, which had the following two settings files for the CLI, stored in the interplay folder:

  • interplay.json for the configuration settings
  • interplay.js (optional) for the modifiers functions and event handlers

CLI 2.x.x uses a slightly different settings file structure from CLI 1.x.x. to accommodate new features and more flexible deployment to different target projects. It now uses a new .interplay folder containing:

  • interplay.config.js that combines the settings
  • targets.json which can contain multiple team/project targets for your deploys. It defaults to one single default target. This allows you to easily deploy the same repo to different projects in Interplay

We can help you update your settings to the 2.x.x format - please contact us when you are ready to upgrade.

Example Handling in 2.x.x

CLI 1.x.x had only limited control of which component instances in parsed story/docs files were selected for import as examples (presets) - a Button example (preset) could be generated from instances in Button.story.js, but could also be generated from a Button instance found in Card.story.js and the user had limited control over which was used.

CLI 2.x.x consolidates these parsing modes into a single parsing mode, and now supports example matching rules, which allow you to set rules for which intances will be matched in each file. For example you can specify:

  • when parsing Button.story.js, only use instances of Button as examples
  • when parsing Icon.story.js, ignore the story's Layout and Spacing components and only import all the components whose path matches src/components/icon/

Because of this different processing, a slightly different set of examples will likely be returned by CLI 2.x.x compared to CLI 1.x.x..

Upgrade steps

👉 We would love to help you upgrade - please let us know and we can run through these steps on a call together.

  1. Install CLI 2.0.0 using: npm install -g @interplay/cli @interplay/cli-plugin-react
  1. Run interplay --version to verify the correct latest version is showing
  1. Run interplay init to select the new or existing project you are importing to. This will create 2 new template settings files:
    1. .interplay/interplay.config.js


  1. Delete the teamId and projectId from your old interplay/interplay.json . The CLI will use the project you selected in step 3 (stored under default in targets.json file.
  1. Cut and paste the remaining settings from interplay.json and interplay.js into interplay.config.js
  1. Adjust the default presetRules in interplay.config.js as required for your repo (we can help you do this)
  1. Run the stages of the new CLI in sequence and check each stage completes as expected:
    1. interplay build - will output build to .interplay/stage/files

      interplay parse - will output config to .interplay/stage/config

      interplay deploy - deploys the files and config from .interplay/stage together with any local include files or deploy files specified.

      (You can run all stages at once using interplay with no parameters)

  1. You can rename your old interplay folder to archive it, as it is not used by CLI 2+. Please update your gitignore settings to save your new CLI config
    1. //.gitignore
      //ignore subfolders of .interplay unless you have added files to save

CLI settings types file (config.d.ts)

The config.d.ts file is created in your repo when running interplay init It is used to help validate your CLI settings. You can update this file to the latest types for your installed CLI by running interplay init again, choosing the same destination design system in Interplay.

Did this answer your question?