Code components

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.

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.

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

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

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>
);

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

//interplay.config.js

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

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

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

2. Add a key corresponding to export name of the parent component

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

interplay