Once the exporter package is built, it can be invoked to produce whatever output it defines — which can be text files, assets, resources or really just about anything else. But what exactly happens when exporter gets invoked? Here is a brief overview how it works.
Step 1: Context selection
In order for the exporter to know what data to use, a context is constructed. The context consists of:
- Target workspace
- Target design system
- Target design system version
- Target brand (optional)
- Target theme (optional)
This means that a single exporter can run against very different contexts and produce different results, simply by targeting a different design systems/versions, by applying different brands, themes and so on.
VS Code
For VS Code, the context is whatever you have selected when setting up the VS Code Supernova extension. You'll see your current selection/context in the panel provided by the extension.
Supernova pipelines
For exporters invoked through pipelines, the context depends on the configuration of the pipeline. The workspace will always be the one where the pipeline was created, and other options such as design system or its version can be configured on each pipeline separately.
In the code
Finally, once the context is provided, it can be accessed in the runtime through the context property in the main export function of the exporter.
This is important because most of the SDK functions require you to provide the target from which you want to pull the information — be it tokens, components or anything else.
Step 2: Executing the main export function
Once the context is provided and Supernova validates that everything is correct (provided the token has access to the requested workspace and so on), the main export function is fired.
We have a dedicated section to the main export function, but a TLDR is that it is the only function that gets automatically executed and must be present for every exporter. The signature of the function is as follows:
Pulsar.export(async (sdk: Supernova, context: PulsarContext): Promise<Array<AnyOutputFile>>
The function gets context and the SDK object which gives access to every piece of data in Supernova. You can learn more about the SDK and its capabilities in the dedicated section.
Whatever the exporter does, the output from this function is what matters. The export function will produce files which will then get written into various destinations based on where the exporter got invoked. Files can be anything ranging from CSS definitions to SVG icons to anything else.
There are several different types of files the exporter can produce which will differ in the content/behavior.
Step 3: Writing the output
Once the exporter produced the files, the export ends and the output gets written into the destination. The output destination for each file will consist of two parts:
- The root directory of the export
- The relative path of the file to the root
As an example, let's say we want to write colors.css into a directory called design-system in our repository. The file is produced by the exporter, and the exporter names the file and also assigns it a relative path. This means that exporter is responsible for structuring its output, but it is not responsible for knowing where to write that output.
The root directory is assigned by the invocation target — VS Code or the pipeline that fired the exporter.
VS Code
For VS Code, the root directory of the export will always be .build folder in the root directory of the exporter package you are developing (gets created automatically when running the exporter for the first time)
Supernova pipelines
For exporters invoked through pipelines, the root directory will be whatever repository you have selected as target to open pull request to. Additionally, pipelines allow you to specify a folder within your repository to use as the root instead.
Going back to our example, we'd configure the pipeline to target relative path /design-system, and we'd let the exporter name the file as colors.css. You can learn about how to do that in the next section.
Step 4: Opening a pull request
Once the exporter run is finished, if the exporter was invoked through the pipeline, a pull request will be usually opened (depending on the configuration) which will contain the delta between last commit and whatever was generated by the exporter.
Now that you know how the exporters work from on a high level, let's look into the main export function where all the magic happens.