Run exporters locally

Using the Supernova CLI utility, you can run any exporter package directly from your command line. There are many use-cases where CLI-powered exporters are extremely powerful, such as:

• You are unable to use pipelines because you can't give access to private repositories due to security limitations / rules yet you still want to use exporters to deliver code/assets to your codebases
• You want to to run exporters behind company VPNs
• You want to have fine-grained control over when exporters run
• You want to integrate exporters with your CI/CD pipelines and with release lifecycle
• You want to integrate exporters with events in your repositories, such as GitHub actions
• You want to run exporters as part of your versioning cycle
• You want to use exporters locally from your command line

This guide explains how to get started with CLI-powered exporters.

Usage

Use the following command to run the exporter in your file system or CI/CD pipeline:

                                                        
                                                        
                                                            $ supernova run-local-exporter \
                                                            --apiKey="[API_KEY]" \
                                                            --designSystemId="[DESIGN_SYSTEM_ID]" \
                                                            --themeId="[THEME_ID]" \
                                                            --brandId="[BRAND_ID]" \
                                                            --exporterDir="[./path/to/exporter/dir]" \
                                                            --outputDir="[./path/to/output/dir]" \
                                                            --allowOverridingOutput
                                                        
                                                            

Command flags

• --apiKey: (Required) Your API key for accessing the Supernova instance.
• --designSystemId: (Required) The ID of the design system you wish to export from.
• --exporterDir: (Required) Path to the local exporter package directory. This needs to point to the root of the exporter where exporter.json is located.
• --outputDir: (Required) Path to the directory where the export results will be saved. This directory must be empty unless allowOverridingOutput is set.
• --brandId: (Optional) The ID of the brand to export. This is required if the exporter package is configured to use brands.
• --themeId: (Optional) The ID of the theme to export. This is used only if the exporter package is configured to use themes.
• --allowOverridingOutput: (Optional) A boolean flag that, when enabled, allows the CLI to override existing files in the output directory. When disabled, if the exporter produces a file and tries to write to a path that already has a file, it will result in an error.

Example

Here is an example explaining how to use the command properly:

                                                        
                                                        
                                                            $ supernova run-local-exporter \
                                                            --apiKey="fjdakl-gfa1234-afgafk" \
                                                            --designSystemId="86" \
                                                            --themeId="123456-123456-123456" \
                                                            --brandId="654321-654321-654321" \
                                                            --exporterDir="./exporters/css" \
                                                            --outputDir="./design-system/styles" \
                                                            --allowOverridingOutput
                                                        
                                                            

Let's break down the command:

Obtaining an API key and designSystemId

First, you'll need an API key and design system you are targeting for this command to run. Learn how to get them here.

Obtaining the themeId and brandId

For exporters that use themes or brands, you'll need the themeId and brandId respectively. You can use the describe command to figure out which ones to use.

How do I know when to use brandId and themeId?

This is configured by the exporter. Usually, exporters that work with styles, tokens, components and assets will at least require you to provide the brandId. Each design system contains at minimum a single brand containing all your data, even if you don't have the multi-branded functionality enabled.

However, some new exporters already provide you with the option to export tokens with theme overrides (such as the exporter for CSS definitions). In this case, themeId is required. If your exporter supports theming capabilities and you don't provide the themeId, no theme will be applied but no error will be thrown as this is still a valid state.

If you want to export your code for multiple brand / theme combinations, you need to run multiple commands with the different configurations provided. In the example above, the exporter will run against the brand 654321-654321-654321 in the design system 86, and will apply theming from theme 123456-123456-123456. You could omit the theme and the exporter will not apply any theme (the tokens will be exported with their base values).

Setting up the exporter package

There is no setup necessary, as the exporter will run as-is from the folder you'll point to. If you want to test it, just download contents of the CSS exporter repository and set exporterDir to point to where you have saved your exporter.

Setting up the output directory

There is no setup necessary, as the command will create the folder for you if it doesn't exist. By default, an error will be thrown if exporter produces file that already exists in the file system to prevent accidental overrides.

If you want to have your exporter override the existing files, enable allowOverridingOutput which will bypass the protection and will override the existing files in the output directory.

We acknowledge this option will be present in most commands you will run, but we want to make sure you understand the behavior before enabling this functionality first.