Import Code components

Pre-requisites

Interplay currently supports importing React code components.

Before starting the steps below, please ensure you have completed the steps in Preparing to Import

Run commands in this section at the base of your repo. Paths should be entered relative to the base of the repo (so in VSCode you can right click on a file and copy relative path).

1. Specify packages to import

The import settings file .interplay/interplay.config.js is created by the initialize step and controls the CLI import. Saving this file in your repo will allow you to run the import repeatedly - either against a local copy of repo, or automatically as part of a CI process.

Update the interplay.config.js to specify the packages you want to import.

For each package, configure an index file to use as the entry point. For example, to import the @auth0/cosmos package we can add configuration as follows:

//interplay.config.js

framework: 'react',
packages: [ {
	name: "@auth0/cosmos", //Name of package to import
	packagePath: "./core/components/package.json", //Path to package.json
	src: "./core/components/index.ts", //Entry file for component parsing
	build: "./core/components/index.ts", //Entry file for component bundling
	ignoreExports: [], //Exports to ignore when parsing
}],
peerDependencies: {},
alias: { //"": "./aliased/relative/path/" },

`framework`	Framework used for your components to determine parsing/bundling plugin used by CLI. Currently 'react' is supported.
`packages`	An array of config objects - one for each package of components to import from your repo. Each containing: `name` - The name of your repo package to import. This should match the name in your package.json `packagePath` - Path to package.json, from the base of the repo where you are running the CLI `src` - Path to index file for used as entry point for component parsing, from the base of the repo where you are running the CLI `build` - Path to entry point for component bundling, from the base of the repo where you are running the CLI. Often the same path as the src if the CLI is building your code, but you can also specify a custom build here. If not specified, the `src`path is used as the build entry point too. See Building your components for more details. `ignoreExports` - An array of export name strings to ignore in the index specified in `src`. Only needed if your `src` index file contains exports you don't want configured as components in Interplay.
`peerDependencies`	object containing package names that should be built as externals when bundling your code. (React and react-dom will automatically be treated as peerDependencies).
`alias`	Object containing any aliases required to resolve paths in your code. These aliases are passed to webpack and also used to find the component source code to parse. Can be: • A relative path from base of repo - in which case it must start with a dot, • or it can be an npm package name (i.e. mapping one name to another)

2. Build your code components

When you have entered your package settings, use the CLI to build your code. It uses webpack internally:

interplay build

The CLI will output the build(s) to the .interplay/stage/files/interplay/build folder, ready for deployment to Interplay.

You can also provide your own custom build, or customise the webpack settings used by the CLI.

3. Parse your components

The CLI uses the same package settings to parse your component source code, to generate JSON config telling Interplay about your components and their props.

To parse your components:

interplay parse

The CLI uses the src entry point index file to find the source code of your components. It parses the components and properties to generate JSON config describing your components.

This generated config is output to .interplay/stage/files/interplay/config/parsing.json, ready for deployment to Interplay.

4. Generate example config

Once we have parsed the components we are ready to create examples for them.

Examples (also known as presets) are useful configurations of your components that you publish to use in Figma. For example, you might have Primary and Secondary examples for your Button component.

Once you publish your design system, your examples will be available in the Figma plugin to insert into your design, where you can customise them further by editing the component props. Only components with examples will appear in the Figma plugin.

It usually easiest to generate examples from JSX files such as Storybook files in your repo. To generate the examples, we tell the CLI to look for instances of your components in JSX and parse them into example configurations:

//interplay.config.js

//Specify files to parse looking for component instances to use as presets. //Can be list of local paths or glob pattern.
presetPaths: ["core/components/**/*.story.tsx"],


//Specify rules for which component instances parsed should be used as presets
presetRules: [
{
	//matches component instances whose name matches first part of filename
	presetPath: ".*/{componentName}.",
	limit: 5, 	//per-component, per-file limit
},
{
	//match component instances whose name matches folder in preset file path
	presetPath: "{componentName}/",
	limit: 5,
},
//add more preset rules here
]

To control this example generation process there are two settings for the CLI - which files to look in, and what instances to parse in each file:

presetPaths - Glob pattern resolving to files that contain instances of your components in JSX. e.g. storybook files or documentation examples.

presetRules - Matching rules specifying which component instances found in the presetPaths files should be configured as examples. The rules in the example above will import e.g. Button from Button.story.tsx, Card from Card.story.tsx etc. but ignore instances of other components in those files.

Once you've added these settings, run the parse step again to generate the examples config. This time it will parse both the component source files and the files specified in presetPaths:

interplay parse

After the CLI completes running, the output file .interplay/stage/files/interplay/config/parsing.json should now include components and examples ('samples' and 'nodes').

5. Deploy to Interplay

Now we are ready to deploy the build and generated config JSON to Interplay. To do this, run the deploy command:

interplay deploy

The deploy command will load and validate the config found in the stage folder and then send the build and JSON to Interplay.

At the end of the deploy, a URL will be provided to click through to your project in Interplay.

6. (Optional) Configure component styling

Include a required stylesheet (CSS) or font file

Some component libraries require a CSS file to be present on all pages displaying the components. You can specify this:

By specifying a local path or URL in the includePaths setting for the CLI, in which case the file will be included on the next deploy from the CLI.

Or by adding a URL in your design system settings online at Settings > Includes

Add a wrapper component

If your components need a wrapper component to providing required context and styles, you can add it to your import. Interplay will wrap your components in this wrapper component wherever it displays your components.

Identify your existing wrapper component or create a custom one. Your wrapper component must:

Accept and render the children prop (so that is can wrap the child components. Include components do not require this)

Set any required Providers

Set default values for any required props such as a default theme.

Be exported from one of the packages you are importing to Interplay i.e. it must be available in your imported builds.

Here is an example wrapper component. As you can see, you can use multiple layers of providers if required:

import React from 'react';
import {Provider as StyletronProvider} from 'styletron-react';
import {Client as Styletron} from 'styletron-engine-atomic';
import {BaseProvider} from '../../src/index.js';
import {LightTheme} from '../../src/themes/index.js';
const engine = new Styletron();
export const ThemeWrapper = ({children}) =
 (
	<StyletronProvidervalue={engine}>
		<BaseProvider theme={LightTheme}>{children}</BaseProvider>
	</StyletronProvider>
);

Once you've created your wrapper code, you can save this to your existing components folder, or store in the interplay folder in your repo.

2. Add the wrapper component to your index file

For Interplay to be able to run your wrapper component, it needs to be included in the components build created by the CLI. To do this, add your wrapper to the index file exporting your components so that it is imported in your next run of the CLI. If you are using a custom build you will need to run that to re-build your index before running the CLI to import the new custom build.

//index.js
export { ThemeWrapper } from "./components/ThemeWrapper.js"

3. Configure the wrapper component in the CLI settings

Next we tell the CLI which of your components to set as the wrapper. The setting takes the form packagename/ExportName:.

//interplay.config.js

//e.g. package
"wrapperComponent": "mypackagename/ThemeProvider"

//e.g scoped package
wrapperComponent": "@myscope/mypackagename/ThemeProvider"

4. Re-run the CLI

Once the wrapper is added to the index, the CLI will then pick it up on the next import run, bundling it with the other components as usual.

Include a global styles component

Some component libraries require one or more global styles components to be present to provide styles to the components (usually instead of a wrapper). You can follow the steps above as for the wrapper, except instead of adding the wrapperComponent CLI setting, you will set it as an “Include” component in the settings of your Design System in Interplay i.e. :

Identify or create your include component

Add it to your component index if not already present (then run your custom build if you are using one)

Run the CLI to re-import your components

In Interplay, navigate to your Design System > Settings > Includes and add the component(s) to be included on each page with your components.

👉

You may wish to re-generate all the navigation thumbnails for your presets once your components are styled correctly. You can do this via: Design system Settings > Includes > click "Regenerate Thumbnails" button at the end of the page.

7. (Optional) Configure subcomponents

For the import, we define subcomponents as those components which can ONLY work when running inside certain other components - i.e. they would error if you tried to run them on their own.

To define subcomponents:

Add the componentSettings configuration key to the package in the CLI settings file

Add a key corresponding to export name of the parent component

Add an array containing the export names of the subcomponents

//interplay.settings.js

packages: [ {
	name: "@example/example", //Name of package to import
	packagePath: "./package.json", //Path to package.json
	src: "./src/index.ts", //Entry file for component parsing
	build: "./dist/index.ts", //Entry file for component bundling
	ignoreExports: [], //Exports to ignore when parsing
	componentSettings: {
		Accordion: {
        subComponents: ["AccordionActions", "AccordionDetails"]
		},
	}
}],

In this example, AccordionActions and AccordionDetails components only work if they are running inside Accordion, so they are added as subcomponents in the package config.

Note that subcomponents definitions are not fixed to how the code exports are structured. You might have a Tab component that is exported from a parent Tabs component as Tabs.Tab, but if Tab does not error when run outside Tabs you don’t need to configure it as a subcomponent in Interplay.

8. Commit your CLI settings files

Once your import is working correctly, you can commit your settings files to your repo. This allows you to run the CLI again in future, either locally or in your CI environment.

Check in the following files in your .interplay folder:

interplay.config.js

targets.json

config.d.ts

The files generated during the run of the CLI can be excluded. For git repos you can do this with an entry in your .gitignore file

.gitignore - exclude subfolders of .interplay folder unless you have saved required files in those subfolders

.interplay/*/

9. Run CLI again to stay up to date

As your code repo changes, you can update your components and presets in Interplay simply by running the CLI again. You can do this locally from the same working directory as your initial import, or as part of your CI process.

Now that your interplay.config.js settings are configured, you can run all the CLI steps with one command:

interplay

The CLI will pick up your saved settings and use them to:

Deploy any configured token files again

Build, parse and deploy any configured components and presets again

Any config changes to your design system will be tracked as a new entry in the version history of your design system project.

For more information about running the CLI as part of your Continuous Integration process, please see: Continuous Integration

Component Import FAQs

Why has the CLI created component config for index exports that are not components?

The CLI does not check whether the exports from your index file are actually components. Attempting to detect this in the parser can lead to false positives and negatives and unpredictable imports. So component configuration is created for all of your exports.

You can control what components are imported from your repo in 2 different ways:

Create a component index that only exports the components you want to import, and set this file as the parsing entry point, in the `src` field of your CLI package settings. (You can still use a different, more complete index as the build entry point or provide your own build. Use the same export name for each component in the two files.)

Alternatively, use the `ignoreExports` function to tell the CLI to ignore certain exports from your component index. No component config will then be generated for these exports.

Why is my preset not displaying any visible UI?

This can occur for a number of reasons:

The component preset has no content Some components are meant to be containers of content, but do not have any UI elements themselves. e.g. div elements. To resolve this issue, add content into the preset.

The component preset has no width or height Some components do not force a min-width and instead fill the container space. However, as the preview container does not have any defined width by default, this means nothing is displayed. To resolve this error, set a width on the preset by choosing Edit Preset and setting a width in the property panel on the right hand side.

This is a non-visual component If this is the case, we recommend deleting the preset as there is nothing to display

Why doesn't my React component show a children property in Interplay?

The properties displayed for each component in Interplay are controlled by the JSON that is created when parsing your component source code. In React it is quite common that you have not defined a children property in your component source code, so it is not created in Interplay.

You can either define the children property in your component propTypes or typescript Props and run the CLI import again, or you can add the children property by editing the props in Interplay. Usually with type 'Array of node'.

Alternatively if you use the CLI to generate a component preset that includes a value for the children property, the children property will be automatically added if it is not already present.

Why does my component have the wrong display name in Interplay?

If you define a displayName in your React component code, that name will be used in Interplay.

If no displayName is defined, a name will be derived from the file name of the file containing the component or the named export.

You can override the name generated by the parsing by editing the component's display name in Interplay. To do this, click the component name and enter the new name. Your override will be reapplied to future imports from your repo.

My components require a theme or other context to be passed to them. How can I do that in Interplay?

React components often require context information to be passed to them, usually at the base of the app consuming the components. In Interplay you can do this by specifying a wrapper component as in step 6 above.