Installing and Running the CLI

Overview

The Interplay CLI can help you create a UMD build of your components and generate config for Interplay by bundling and parsing your code automatically.

Only the compiled build and the generated config is sent to Interplay, not your source code.

When creating your CLI settings we recommend running the build, parse and deploy stages separately. Once each of the stages are completed correctly, you can then run all of these stages automatically with a single interplay command as part of your CI process to keep Interplay and your design tools up to date.

CLI Requirements

What you need to provide

To import your component code using the CLI you will need to provide:

  1. An index file for each package you want to import, that exports your components individually as named exports e.g.:
  2. //e.g. src/index.js 
    
    //re-exporting default imports
    export { default as Button } from './Button';
    export { default as ButtonGroup } from './ButtonGroup';
    
    //re-exporting named imports
    export { Card } from './Card';
    export { Footer } from './Footer';
    ...etc
    

    For a monorepo/multi-package repo you will need to provide an index file for each code package that you want to import.

    This index file may be an existing one used for your components, or you can create a custom index for the import that only exports the components you want available in Interplay.

    You can also optionally provide custom webpack build settings or a custom build of your components if required.

  1. Usage examples of your components to use as presets
    1. For React components you can provide JSX examples, e.g.

      //e.g. buttongroup.preset.js
      
      import React from 'react';
      import { Button, ButtonGroup } from 'reactstrap';
      const basicButtonGroup = (props) => {
        return (
          <ButtonGroup>
            <Button>Left</Button>
            <Button>Middle</Button>
            <Button>Right</Button>
          </ButtonGroup>
        );
      }
      export default Example;
      

      You can re-use existing files containing instances of your components in JSX such as storybook files or documentation example files.

      The following formats are parsed:

    2. Javascript and Typescript - e.g. files using storybook CSF or storiesOf format or other exported JSX examples
    3. Markdown files containing JSX code blocks
    4. MDX files
  2. Interplay account
  3. In your browser, please navigate to https://app.interplay.io/ and check you can login to your workspace before running the import.

Framework support

Currently React code components are supported by Interplay.

We will be adding support for Vue.js and other frameworks soon.

CLI Runtime support

The Interplay CLI runs on Node versions 12, 14, and 16 on Windows, MacOS and linux. Typically it is run first on your local workstation to create your settings, then can run as part of your CI process.

Preparing to import

1. Clone your code repo

We'll run the CLI against a local copy of our code repo. If you don't already have a local copy or your code, clone the repo using your usual source control.

For example, using git:

git clone https://github.com/auth0/cosmos.git

2. Install your package dependencies

The CLI will bundle your code for deployment, so we need to install your package dependencies. Usually this is done using npm or yarn, but use whatever your normal approach is to install the npm dependencies for your repo.

For example, using yarn:

yarn

3. Install the CLI

It is usually easiest to install the Interplay CLI and its React plugin globally using npm:

//install the beta for these instructions
npm install -g @interplay/cli@next @interplay/cli-plugin-react@next

4. Initialise your CLI settings

👉

Please run the CLI at the base of your repo so the CLI is aware of all the packages in your repo. Enter all settings paths relative to the base of your repo

The first step in using the CLI is to initialise your config by registering a new project to contain your code. In the root folder of your repo:

interplay init

Running this command will popup a browser for you to specify the project to import to:

image

Set the project name you would like to use and click Continue.

Two config files will be created in the .interplay folder in your repo. These files control the import:

  • targets.json - this controls the target team and project you are importing to
  • interplay.config.js - this controls all the other settings required such as the packages to import, the files to bundle and the settings to use when parsing your presets.

In the sections that follow we'll update the relevant config and then run the relevant CLI command to build , parse and deploy your components.

Now you can configure your import settings - please see: Configuring CLI Settings