<aside> 👉 Before starting this step, install the CLI and initialize your settings files: Installing and Initializing the CLI ‣
</aside>
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 your local repo, or automatically as part of a CI process.
In this section we will work through a new import in stages, adding configuration settings used by each stage.
<aside> 👉 Run commands in this section at the base of your repo. Paths should be entered relative to the base of the repo (e.g. in VSCode you can right click on a file and copy relative path).
</aside>
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: {
//"<alias string>": "./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:
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:
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/confi/parsing.json, ready for deployment to Interplay.
For more details about parsing your components, please see:
Once we have parsed the components we are ready to generate presets.
Presets are useful configurations of your components that your designers can use as a starting point for using the component in your design tools.
You can manually create presets through the Interplay UI, but for large numbers it usually easier to generate them from JSX in your repo.
First we need to update the config file to tell the CLI which files to look in for instances of your components. We can do this with the presetPaths setting:
//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: [
{
//Specify which preset file(s) to match with this rule
presetPath: ".*/{componentName}.", //e.g. matches component instances whose name matches first part of filename
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
]
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 other component instances in those files.
Now we can run the parsing 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.
For more details about generating presets including setting preset rules, please see:
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.
Once your import is working correctly, you can save your settings to your repo.
Please check in the following files in your .interplay folder:
For git you can do this with an entry in your .gitignore file
# .gitignore - exclude subfolders of .interplay
# unless you have saved required files in those subfolders
.interplay/*/
The files generated during the run of the CLI can be excluded from the repo.
As your code repo changes, you can update your components and presets in Interplay simply by running the CLI again from the same working directory as your initial import.
You can run build, parse and deploy in one step:
interplay
The CLI will pick up your saved interplay.config.js settings and use them to build, parse and deploy your code and presets again.
You can add the CLI to your CI process to keep Interplay updated automatically with changes in your repo:
Perhaps the easiest way to understand the component import settings for the CLI is to see how they can be used to import other code libraries:
Example component import settings
To upload tokens from your repo, you can create one or more JSON token files containing your tokens, usually either as a common reference file or from a custom script that creates these JSON files from elsewhere in your repo.
The CLI can current import the W3C Community Draft Design Tokens format. We've summarised this here: Design Tokens JSON formats
You can also upload tokens in ThemeUI format through the UI (the CLI will support this format too soon).
Once you have created the JSON file, you then tell the CLI to pick up those files using the designTokens setting in interplay.config.js
The easiest way to understand how to use this setting is from an example:
designTokens: {
default: {
paths: [".interplay/init/default.tokens.json"],
format: "[email protected]",
name: "Default Theme",
},
dark: {
paths: [".interplay/init/dark.tokens.json"],
format: "[email protected]",
name: "Dark Theme",
},
},
The designTokens CLI setting is an object keyed on themeId . In the example above, two themes are specified - light and dark.
Each theme takes the following settings
paths - specifies a glob pattern which resolves to the JSON files to import.
format - a string identifying the format of the JSON provided. Currently the W3C community group draft format is supported, denoted as [email protected]
name - the display name of the theme that will be displayed in Interplay.
Note that the structure of the tokens for each theme is expected to be consistent, so that swapping themes in Interplay would display the same token structure but with potentially different values for the different themes.
When the CLI processes these designTokens it will validate the JSON config and create:
Once tokens are in Interplay they can be dynamically passed to your components as a theme object, if your code components support that.
This allows you to edit tokens in Interplay and interactively see the effect of your changes on your components.
To set this up usually requires:
extension of type computedValue in your project settings that scripts the conversion of your live tokens data into a theme object.Please contact us for help in setting this up for your components.
Next: Curating your import