Parsing components

Once you have configured your CLI settings, you can parse components using the CLI:

interplay parse

To set up your CLI settings, please see Running the CLI

This page describes how you can control the specific config generated for each component.

Curating Components

Once you have got the basic import working, there are various ways you can control the configuration 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. Ignoring index exports

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.

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.

Modifying Component Config

Component config structure

Before attempting to modify the component config it is useful to see an example of how it is structured. 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"
		},

Component

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 string, number, boolean, object, date, array, Node, Event, Component, fnNode, unknown

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)

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

//Button.js
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

//Button.ts
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.

Components

description

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 {

path (CLI 2.0.0+)

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 {

Props

description

As for components, 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,

ui.hidden

You can hide component properties by setting the ui.hidden attribute, using the @interplayignore tag (CLI1.x.x) or @interplayhidden (CLI 2.0.0)

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

type (e.g. for Render Props)

There is a shortcut tag @interplaytype available for overriding type for a prop.

We recommend type information for props setting this via propTypes or typescript type definitions rather than JSDocs as outlined above.

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

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:

/** 
 * Here is the description for this prop
 * @interplaytype string
 * */
id: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),

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

/** Description of the render prop
* @interplaytype () => React.ReactNode
*/
  myRenderProp: PropTypes.func.isRequired,

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 (string, number, boolean, 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

Advanced CLI settings

Filtering inherited properties

Typescript components often define component properties via Props that inherit common properties.

In some cases the inheritance structure can lead to many hundreds of properties on each component, in which case it can be useful to filter out common inherited props to leave only the component-specific properties configured.

By default the CLI filters out properties inherited from the following type names:

filteredTypes: [
      'AllHTMLAttributes',
      'HTMLAttributes',
      'ButtonHTMLAttributes',
      'InputHTMLAttributes',
      'SelectHTMLAttributes',
      'TableHTMLAttributes',
      'TextareaHTMLAttributes',
      'FormHTMLAttributes',
      'LiHTMLAttributes',
      'OptionHTMLAttributes',
      'DOMAttributes',
      'AriaAttributes',
      'ClassAttributes',
      'Attributes'
 ],

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

Any component properties inherited from these types will be removed from your component configuration, unless the prop is used in one of your presets. Any properties used in your presets 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 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<HTMLButtonElement, DropdownButtonProps>(
	//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: