Exporter anatomy

Understanding the structure of an exporter is crucial for both usage and development. An exporter package consists of specific parts that ensure its functionality and also compatibility with all the parts of the system.

Minimum Viable Package

In order to have an exporter package that works and can be executed both locally and with Supernova pipelines, you have to, at minimum, create the following structure:

                                                        
                                                        
                                                               - exporter.json
                                                           - config.json
                                                           - package.json (+package-lock.json)
                                                           - README.md
                                                           /src
                                                              - index.ts
                                                           /dist
                                                              - index.js
                                                        
                                                            

The exporter packages are npm-like packages, but are not published to npm — instead, they are published to our own Supernova distribution platform, the store (or installed to the workspace if you don't want to share them with the world and only use them for your own purposes).

Here is the list of the important components and what they mean:

Export configuration: exporter.json

Main package configuration file. When installing the exporter to Supernova, this is the file that gets checked for things like id, the exporter name which will show up in the store/workspace and so on. Here is a full list of properties that the exporter.json can contain.

• id: A unique identifier for the exporter. It follows the pattern "[COMPANY_NAME].exporter-[PLATFORM]", making it easy to differentiate between exporters from different companies or for different platforms.
• name: A human-readable name for the exporter, typically representing the platform or technology it targets, like "[PLATFORM] Exporter".
• description: A concise description of what the exporter does. It typically describes the transformation, such as "Export your design system data into [PLATFORM / TECHNOLOGY]".
• author: Name of the individual or team responsible for creating the exporter.
• organization: The name of the company or entity that owns or released the exporter.
• homepage (optional): A URL pointing to the exporter's homepage or main documentation page. If not applicable, this field can be omitted.
• version: Specifies the version of the exporter. It must follow semantic versioning, X.Y.Z. Version needs to be bumped up when updating the exporter, otherwise the update will be rejected by the Supernova store.
• usesBrands & usesThemes: Boolean values indicating whether the exporter utilizes brands and themes respectively.
• executable: The relative path to the main .js file (entry point) of the exporter, like "/dist/build.js".
• engine: Indicates the version of the engine the exporter is running. All new exporters must use latest option to use the new execution engine. For legacy exporters not written with TypeScript, omit the engine field completely or use legacy option.
• tags: An array of tags related to the exporter. These can help categorize or identify functionalities provided by the exporter, such as 'Tokens', 'Assets', etc. Tags will be used to group the exporters in the Supernova store.

Main executable: index.js

This JavaScript file, specified in the executable field of exporter.json, holds the entire functionality of the exporter. This file gets compiled from all the .ts files present in the exporter package using webpack.

The default packages of the exporters come with webpack configured - just run npm run build to create the file for you, or npm run dev to have the webpack continuously build as you develop.

Main code entrypoint: index.ts

With default exporters, the functionality gets written into index.ts file and compiled down to index.js that gets executed. The entrypoint must contain a single execution function about which you can learn in a dedicated section.

Configuration file: config.json

This configuration file allows users to adjust the behaviors of the exporter without modifying its main code. For sophisticated exporters, this configuration can vastly change how any one exporter behaves. Follow the export configuration section to learn more.

Configuration type interface: config.ts

Adjacent to config.json, config.ts provides type interface for the exporter for the configuration it exposes. Follow the export configuration section to learn more.