Control parsing

CLI settings and JSDocs in your repo

Once you have configured your CLI settings, you can parse your component source code using the CLI to generate JSON config describing your components. This page describes how you can control the specific config generated for each component.

Controlling which components are imported

There are 2 ways to exclude components from the Interplay config created by the CLI:

1. Custom component parsing index

The easiest way to control which components are imported is to create a custom index file for Interplay that only exports the components you want in Interplay.

If you use this same index file for parsing and bundling (i.e. in the src and build package settings in your CLI settings) then both the build and the config will only contain the components in the index.

Your index file must:

  • Export your components individually (as named exports or default)
  • Use the same export names as the build you provide (this will of course be the case if you use same index for parsing and bundling).

After creating your custom index, update the src setting for the relevant package in your CLI settings file to tell the CLI to use this custom index.

2. ignoreExports setting

If you are using an index file that contains exports you want to exclude from Interplay, you can set a list of exports to exclude using the ignoreExports CLI setting on that package.

Use this approach for exports that still need to be present in your build (for example, if they are used by other components) but you want to avoid having them registered as components in Interplay.


Component config structure

Before attempting to modify the component config it is useful to see an example of how it is structured. After running the parsing step you can see the config the CLI has created for your components in your .interplay/deploy/code.json file.

"< identifier value >": {
	"id": "< identifier value >",
	"name": "Button "description": "Here is the component description",
	"code": {
		"packageName": "reactstrap",
		"exportName": "Button",
		"lib": "reactstrap"
	"path": "Actions/Buttons",
	"props": {
		"variant": {
			"name": "variant",
			"type": "string"
		"size": {
			"name": "size",
			"type": "string",
			"enum": [ "small", "medium", "large" ],
			"default": "medium",
			"ui": { "hidden": true }
		//...(more props) },
	"relativePath": "src/Button.js"


name - the component name to display in Interplay

description - the description text displayed in Interplay

code - this block specifies how the Interplay accesses this component in the your build

path - Interplay folder structure for Button (available CLI 2.0.0+)

Component props

type - how Interplay should treat the value set for this prop

  • Currently a single type is supported per prop
  • Current allowed values are stringnumberbooleanobjectdatearrayNodeEventComponentfnNodeunknown

enum - sets the allowed values for the prop - these will appear as a dropdown in properties panel

ui.hidden - prevent prop displaying in Interplay and plugins (can still edit online in Edit Properties)

Controlling Component Config

1. In your component source file

The Interplay parser will generate metadata from the structure of your code. For React components you can set:

displayName - to set the name that Interplay will use for your component. If this is not set it will default to the filename containing the component.

class StatefulButton extends React.Component {
	//(StatefulButton implementation)
StatefulButton.displayName = "Button"

propTypes (react) or type definitions for your props - we recommend controlling property type information information using prop-types or typescript types definitions in your code. The CLI parser will find this type information and use it to generate Interplay configuration.

e.g. Using proptypes to specify the allowed values for a property, which will appear as dropdown in Interplay props panel


import PropTypes from 'prop-types';

//(Button implementation)

Button.propTypes = {
	variant: PropTypes.oneOf(['success', 'warning', 'error']),
	//more Button props

e.g. Using typescript to specify allowed values


export type Size = 'small' | 'medium' | 'large'

export interface IButtonProps {
	/** The size of the button */
	size?: Size 					//using variable
	variant?: 'success' | 'warning' | 'error'; 	//inline values

	//more Button props

const Button = ({ children, ...props }: IButtonProps) => {
	//Button implementation

2. Using JSDoc tags

You can modify the component config generated by adding JSDoc tags to the component definition, or to the props definitions.



You can add normal JSDoc comments to your components and their properties and they will be used as the component description in Interplay when discovered by the parser:

* Normal JSDoc description will be set on component by Interplay
class Button extends React.Component {  }

You can set a custom description for Interplay with the @interplaydesc tag

* Default description of Button
* @interplaydesc Custom description parsed by Interplay CLI
class Button extends React.Component { }


You can create and control the folder that your component is displayed in by setting the path attribute using the @interplaypath tag. On running the import, the equivalent folders will be created in Interplay if they do not already exist:

* Description of Button component
* @interplaypath Actions/Buttons
class Button extends React.Component { }



As for components, you can set description on props using a normal jsDocs tag on their propTypes in javascript or in type definitions for Typescript...

* The size of Button to display *
size: PropTypes.string,

...and you can set a custom description for Interplay with the @interplaydesc tag

* The size of Button to display
* @interplaydesc Custom description parsed by Interplay CLI
*/ size: PropTypes.string,


You can hide component properties by setting the ui.hidden attribute, using the @interplayhidden tag

/** @interplayhidden */
ref: PropTypes.string,

type (e.g. for Render Props)

There is a shortcut tag @interplaytype available for overriding type for a prop. Where possible we recommend setting type information for props via propTypes or typescript type definitions rather than JSDocs as outlined above.

There are two cases where you might need to modify the type

  1. You need to override the value the parser finds. e.g. if the type was not parsed, or there are two different types allowed by the code and we need to specify which one to use:
    1. /**
      * Here is the description for this prop
      * @interplaytype string
      id: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
  1. Another case where you need to tell the parser the type to use is with renderProps. To the parser, a render prop will look like any other function property. We can tell the parser this is a render prop by assigning a tag with the special value of () => React.ReactNode this will cause the type of 'fnNode' (function node) to be set in the config
    1. /** Description of the render prop
      * @interplaytype () => React.ReactNode */
      myRenderProp: PropTypes.func.isRequired,<br>

Setting other attributes on both components and props (CLI 2.0.0+)

JSDocs can be also used to modify or set other config attributes by using one or more interplay tags, which use the format @interplay {type} attribute - value

  • type is the type of value you are providing (stringnumberboolean, object or array)
  • attribute is the dot path to the attribute you are modifying from where the JSDoc tag is applied
  •  is used as delimiter between attribute and value
  • value is the value to set, parsed based on {type}

Here are some examples setting attributes on the component object

* Default description of Button
* @interplay {string} description - Custom description of Button for Interplay
* @interplay {string} path - Actions/Buttons
class Button extends React.Component { }

These examples are the equivalent of setting the @interplaydesc and @interplaypath tags above.

Here are some examples setting attributes on a prop declaration.

/** Default description of variant prop
* @interplay {string} description - Here is my override variant description
* @interplay {boolean} ui.hidden - true
* @interplay {array} enum - ["primary", "secondary", "danger", "warning"]
* @interplay {number} default - 0
variant: PropTypes.string

3. Programmatically modifying component config

If you are using the CLI, you can intercept the parsing at different points to programmatically modify the generated configuration. This is done by overriding modifier events in your interplay.config.js file.

More details: Programmatically modifying config

Filtering inherited properties

Typescript components often define component properties via Props that inherit common properties. This inheritance can lead to many hundreds of properties being valid on each component.

It is useful to filter out common inherited props to leave only the component-specific properties configured. When parsing react code repos, by default the CLI filters out properties inherited from the react types path **/node_modules/@types/react/index.d.ts

You can provide your own list of inherited types to be filtered by providing an array of paths in the filteredTypePaths setting in the CLI's interplay.config.js settings file.

Any component properties inherited from types in these files will be removed from your component configuration, unless the prop is used in one of your examples parsed by the CLI. (Any properties used in your examples are automatically preserved in the component configuration.)

Parsing custom component types (typescript)

The React plugin for the CLI uses the excellent react-docgen-typescript library to parse typescript component metadata (augmenting the results with other parsing).

By default this library recognises common react component types, but sometimes does not recognise the component if it is exported as another type. For example:

//DropdownButton.tsx custom type example

import React, { forwardRef } from 'react';
type DropdownButtonProps = {
	//DropdownButtonProps implemented here

const DropdownButton = forwardRef( //DropdownButton implemented here );

type CompoundedType = typeof DropdownButton & { Item: typeof Dropdown.Item; };
const Compounded = DropdownButton as CompoundedType;
Compounded.Item = Dropdown.Item;

export default Compounded; //parser does not recognise this as component

In this case we can tell the parser to recognise this custom type as a component in the CLI settings:

//CLI settings in interplay.config.js
customComponentTypes: ['CompoundedType'],
Did this answer your question?