Code components
Import code components from your repo, creating the configuration settings needed for CI
Overview
To run your code components, Interplay requires a UMD bundle of your components and a JSON configuration file describing them.
The Interplay CLI can help you create these by automatically bundling and parsing your code. Alternatively you can create your own and use the CLI to deploy them to Interplay.
Interplay currently supports React code components, including web components in React components such as Stencil and LitElement.
Pre-requisites
Before starting the steps below, please ensure you have completed the steps in Prepare repo import
The settings file .interplay/interplay.config.js
should already have been created by the init
step. This file controls the CLI import and you’ll populate this file in the steps that follow.
1. Build your code components
Update the interplay.config.js
to specify the packages you want to import from this repo.
For each package, configure a build
index file to use as the entry point for bundling. For example, to bundle the @auth0/cosmos
package we can add configuration as follows:
//interplay.config.js framework: 'react', packages: [ { name: "@auth0/cosmos", packagePath: "./core/components/package.json", build: "./core/components/index.ts", //Entry point for bundling } ], peerDependencies: {}, alias: { //"aliasname": "./aliased/relative/path/" },
When you have entered your build entry points, run the build command:
interplay build
The CLI will bundle each package using webpack with the build entry point you specified, and output the build(s) to the stage folder ready for deployment to Interplay: .interplay/stage/files/interplay/build
You can also:
- provide your own custom build, or
- customise the webpack settings used by the CLI.
2. Parse your components
Next we need to generate JSON metadata that tells Interplay about the components in the build and their props.
The CLI can generate this JSON from either:
- an index file whose exports resolve to the component source code (if your source code is in typescript or defines prop-types), or
- an index file resolving to types definitions for your components.
Create a new index file that only contains the components you would like to use in Interplay. This file must contain individual named exports whose names match the exports provided by your component build.
//use individual named exports export { Alert } from './components/Alert'; export { Button } from './components/Button'; //etc.
Add the path to this parsing index file to the package settings, relative to the base of the repo:
//interplay.config.js framework: 'react', packages: [ { name: "@auth0/cosmos", packagePath: "./core/components/package.json", build: "./core/components/index.ts", //Entry file for bundling //add src or types index to parse (types take priority if both) src: "./core/components/index.ts", types: "./core/components/index.d.ts" ignoreExports: [], //Parsing index exports to ignore } ], peerDependencies: {}, alias: { //"aliasname": "./aliased/relative/path/" },
Once you have added your parsing index setting, parse your components:
interplay parse
The CLI resolves the the parsing index exports to generate JSON config, which is output to: .interplay/stage/files/interplay/config/parsing.json
3. Deploy to Interplay
Now we can deploy the build files and generated config JSON from the stage folders to Interplay:
interplay deploy
At the end of the deploy, a URL will be provided to click through to browse your component metadata in Interplay.

4. Create component examples
To run the components, we provide examples, which are configurations of your components. The configurations are created as JSON which allows designers to use them as customizable starting points in their designs.
Creating examples in Interplay
To check the component build is working, let’s create an example for a component online in Interplay.

Browse to the component in Interplay (e.g. Button) and click New Example.
- Use the example editor to create your example. You can work in JSX in the code panel or use the props panel to create your example.
- You should see a preview of your component in the centre of the screen. If not, please check for any errors in the dev tools of your browser and resolve any build errors before continuing. If component styles are missing you can add them in the next step below.
- Click Save to save your component example.
You can create examples for more of your components in the browser, but for maintaining lots of examples it is usually easiest to import them from JSX files in your repo.
Importing examples from JSX files in your repo
Create example files
In the CLI’s .interplay
folder in your repo, create a new folder called examples
and create a file for each component….

…..using Storybook’s excellent Component Story Format (CSF 2.0 or CSF3.0) or storiesOf format.
//.interplay/examples/Button.example.js import React from "react"; import { Button } from "@auth0/cosmos"; export default { title: "Button", component: Button, }; export const basic = { render: () => <Button>Button</Button>, }; export const primary = { render: () => <Button appearance="primary">Primary</Button>, }; export const secondary = { render: () => <Button appearance="secondary">Secondary</Button>, }; //more examples here
You can create one or two example files initially, adding more later when you are ready.
Generate examples files (optional)
To save time, the CLI can generate an initial set of example files from existing stories/docs files in your repo, in a one-off run to use as a starting point:
//generate CSF 3.0 example files from typical JSX/TSX paths in your repo interplay examples //pass a glob pattern to generate from specific files interplay examples src/**/*.demo.js
The CLI will parse your existing files and then generate example files from any component instances found. You can then edit these generated example files to use as the curated set of component configurations to use in Interplay.
Import your examples
Once you have created one or more example files, run the CLI to parse your components and examples and deploy these changes to Interplay:
//generate updated JSON containing your components and examples interplay parse //deploy build and updated config to interplay interplay deploy
5. (Optional) Configure component styles
If your styles are not bundled with your components, you may need to add styling using the appropriate step for your components:
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.
//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.
6. (Optional) Configure subcomponents
We define subcomponents as those components which should only be used inside certain other components e.g. Menu.Item or Tab.Panel.
To define subcomponents:
- Add the
componentSettings
configuration object 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, as accessed from your build.
//interplay.settings.js packages: [ { name: "@example/example", packagePath: "./package.json", build: "./dist/index.ts", src: "./src/index.ts", ignoreExports: [], componentSettings: { "Accordion": { subComponents: ["AccordionActions", "AccordionDetails"] }, "Tab": { subComponents: ["Tab.Panel"] }, "Radio.Group" { subComponents: ["Radio"] } } } ],
In this repo, 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 only required if the child component should not be used as a standalone component.
7. 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
- example files in .interplay/examples folder
The files generated during the run of the CLI can be excluded.
For git repos you can set this up with entries in your .gitignore
file
#.gitignore - exclude working files under .interplay folder
.interplay/logs/*/
.interplay/deploy/*/
.interplay/stage/*/
8. Run CLI again to stay up to date
Now that your interplay.config.js
settings are configured, you can update your components and presets in Interplay simply by running the CLI again, either locally or as part of your Continuous Integration process.
You can run the CLI’s build
, parse
an deploy
steps again separately or with one command:
interplay
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 parsing index exports that are not components?
The CLI does not check whether the exports from your parsing index file are actually components. Attempting to detect this in the parser can lead to false positives and negatives that you can’t control. You can control what components are imported from your repo by:
- Using a dedicated parsing index file for Interplay (recommended)
- Use the
ignoreExports
package setting ininterplay.config.js
to exclude specific parsing index exports.
Why is my example not displaying any visible UI?
This can occur for a number of reasons:
- The component example 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 example.
- The component example 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, set a width on the preset by choosing Edit Example 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 example 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 discovered by parsing your component source code and any component example files parsed in your repo.
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 unless the CLI parses an example populating children
for that component.
To fix this you can:
- define the
children
property in your component source code and run the CLI again
- add a example file for that component, populating the
children
prop and run the CLI again
- edit the component props in Interplay to add the
children
property, usually as anarray
of typenode
.
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 title 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 shown in step 5 above.
Changes in my code are not showing up in my build in Interplay
If you are using your own custom build you will need to re-build that before running the CLI to bundle and deploy to Interplay.
You can run the CLI’s build
, parse
and deploy
commands in one step by running:
interplay