Importing code components from your repo

In this article we will import code components in stages, creating the configuration settings needed for each stage. If you only want to import design tokens from your repo you can skip this step.

In this article

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 srcpath 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. For more details on these options and troubleshooting builds, please see: Building your components

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.

For more details about parsing your components, please see: Parsing components

4. Generate preset config

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

Presets are useful configurations of your components that you publish to use in Figma. For example, you might have Primary and Secondary presets for your Button component.

Once you publish your design system, your presets 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 presets will appear in the Figma plugin. 

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

//PRESETS SETTINGS in 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 preset 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 presets. 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 preset 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 config .interplay/stage/files/interplay/config/parsing.json should now include components and presets ('samples' and 'nodes').

For more details about generating presets including setting preset rules, please see: Generating component presets

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. Save your CLI settings files

Once your import is working correctly, you can save your settings files to your repo. Please 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 from the repo. 

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/*/

7. 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 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 for your React component, 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 from your build. 

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 we can do this by:

  1. Creating or identifying a wrapper component that sets this context information
  2. Adding this wrapper component to the build by exporting it in our component index
  3. Setting this component as a wrapper on our Design System in Interplay.

For more details please see Wrapper Components

Next: Example import settings