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.

💡
Run CLI commands at the base of your repo. Paths should be entered relative to the base of the repo. (If you use VS Code you can usually just right click on a file and ‘copy relative path’).

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:

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.

Notion image

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.

Notion image

Browse to the component in Interplay (e.g. Button) and click New Example.

  1. 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.
  1. 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.
  1. 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

💡
We use dedicated example files for Interplay so you can see and curate the examples imported, to isolate individual instances and because you typically only want the most useful configurations as examples in Interplay.
 

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….

Notion image
 

…..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. 

  1. 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. :

  1. Identify or create your include component
  1. Add it to your component index if not already present (then run your custom build if you are using one)
  1. Run the CLI to re-import your components
  1. 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:

  1. Add the componentSettings configuration object to the package in the CLI settings file
  1. Add a key corresponding to export name of the parent component
  1. 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 in interplay.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 an array of type node.
 
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
 
Did this answer your question?
😞
😐
🤩