Upgrading the CLI

Updating to the latest CLI version 2.x.x

You can see the current available CLI version on the npm registry

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 preset rules, 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.

Preset 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 presets (examples) - a Button preset (example) 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 preset 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 presets
  • 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 presets 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
  2. Run interplay --version to verify the correct latest version is showing
  3. Run interplay init to select the new or existing project you are importing to. This will create 2 new template settings files:

    .interplay/interplay.config.js

    .interplay/targets.json

  4. 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.

  5. Cut and paste the remaining settings from interplay.json and interplay.js into interplay.config.js
  6. Adjust the default presetRules in interplay.config.js as required for your repo (we can help you do this)
  7. Run the stages of the new CLI in sequence and check each stage completes as expected:

    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)

  8. 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

    //.gitignore 
    //ignore subfolders of .interplay unless you have added files to save
    .interplay/*/<br>
    	

CLI settings types file (config.d.ts)

Here is the current content of the config.d.ts file referenced to validate your interplay.config.js file in your IDE. This d.ts file is created when you first install the CLI

//config.d.ts CLI v2.0.11
export namespace InterplayCLI {
    type PresetRule = {
        /** Pattern matching which preset file(s) match with this rule */
        presetPath: string;

        /** Pattern matching which component name(s) to match with this rule */
        componentName?: string;

        /** Pattern matching which component path(s) to match with this rule */
        componentPath?: string;

        /** Per-component, per-file limit for number of matching instances to use as presets */
        limit?: number;
    }

    type Package = {
        /** Name of a package to import */
        name: string;

        /** Relative path to package.json for this package, from base of repo */
        packagePath: string;

        /** Relative path to component index to use for parsing, from base of repo */
        src?: string;

        /** Relative path to component index to use for build, from base of repo (defaults to src entry above) */
        build?: string;

        /** Relative path to types declaration index (.d.ts) to parse instead of source code */
        types?: string;
        
        /** Specify any exports in the src entry file that should be ignored */
        ignoreExports?: string[];
    }


    type Events = {
        /** modify config after the CLI resolves source files, before parsing */
        resolveComponentsComplete?: (context: object) => object;

        /** modify config after all parsing, before deploy to interplay */
        parsingComplete?: (context: object) => object;
    }

    type Modifiers = {
        /** modify the babel config used to transpile */
        babelConfig?: (config: any) => object;

        /** modify the webpack config used to bundle your build.entry */
        webpackConfig?: (config: any, webpack: Function) => object;  
    }


    type DesignTokenTheme = {
        /** glob pattern returning design token JSON files */
        paths: string[];

        /** format of your tokens JSON */
        format?: string;

        /** display name of this theme */
        name?: string;
    }
    
    export interface Settings {

        /**
         * Specify design tokens JSON files to import
         */
         designTokens?: DesignTokenTheme[];

        /** The framework to import components for. Currently react is supported. */
        framework?: "react"

        /** The component packages to import from this repo */
        packages: Package[];

        /** npm packages to treat as externals when bundling components (react and react-dom are set automatically) */
        peerDependencies?: {
            [key: string]: string;
        }

        /** aliases to use for webpack and resolving import paths */
        alias?: {
            [key: string]: string;
        },

        /** Specify a component to use as a wrapper component (if required) when rendering components. The wrapper component must be exported from the deployed build  */
        wrapperComponent?: string;

        /** run webpack in development mode instead of (default) production mode */
        devBuild?: boolean;

        /** specify asset file size limit for inclusion in the build */
        assetByteLimit?: number;

        /**
         * Specify files to include on pages containing component, in addition to bundle files.
         * Can be list of urls and/or list of relative paths or glob pattern.
         * @default []
         */
         includePaths: string[];

        /**
         * Specify additional files to deploy for components to work.
         * Can be list of relative paths or glob pattern.
         * @default []
         */
         deployPaths: string[];

        /**
         * Specify files to parse for component presets.
         * Can be list of relative paths or glob pattern.
         * @default []
         */
        presetPaths: string[];

        /**
         * Specify rules for choosing components instances to use as presets.
         * @default []
         */
        presetRules: PresetRule[];

        /**
         * Specify names of inherited types whose props should be removed from component parsing result (typescript only) 
         * @default []
         */
         filteredTypes?:  string[];

        /**
         * Specify names of custom types that should be treated as components when parsing component source files (typescript only) 
         * @default []
         */
         customComponentTypes?:  string[];

        events?: Events;
        modifiers?: Modifiers;

    }
}