Parsers Engine

Parsers Engine API reference

Configuration file

The Configuration file has common properties, and some destination specific ones

interface ConfigurationFileCommon {
  version: '2';
  repository: string; // @owner/repository
  rules: Array<ParserRule>;
}

For Specify CLI

interface CLIConfigurationFile extends ConfigurationFileCommon {
  personalAccessToken?: string; // Can be set using the -p flag
}

For GitHub

interface GitHubConfigurationFile extends ConfigurationFileCommon {
  personalAccessToken: string; // Can be set over secret
}

ParserRule

The Parsers Rules help you transform your design tokens and assets the way you want.

A rule is composed of the following properties:

interface ParserRule {
  name?: string;
  parsers: Array<ParserConfiguration>;
};

Name	Type	Required	Description
name	string	false	The name of your rule.
parsers	Array<BuiltInParserRuleConfiguration>	true	The parsers you want to apply to transform your token tree. For further details see Parsers.

In many places you will use many parser rules in a configuration to parallelize the changes you want to apply.

BuiltInParserRuleConfiguration

The Parser Configuration object helps you configure the behaviour of a given parser.

interface ParserConfiguration {
  name: string; // parser name: to-json, to-tailwind...
  output: 
    | { type: 'directory', directoryPath: string }
    | { type: 'file', filePath: string };
  options?: Record<string, any>; // depends on the selected parser
}

Looking for the parsers list and options? 👉 heads up to the Parsers reference

The object is composed of the following properties:

Name	Type	Required	Description
name	string	true	The name of the parser. Choose from all available parsers.
options	Record<string, any>	false	The options relative to the parser you apply. Each parser has its own options. For further details see Parsers.
output	object	true	The output you want the parser to generate. Either a file or a directory.

ParserOutput

The parsers produce different types of outputs based on your configuration and their proper capabilities. If not all the parsers accept an output configuration property, the ones which do always take a standardized type as input.

File

Use case: the parser is expected to produce exactly one file.

type FileOutput = {
  type: 'file';
  filePath: string;
}

Example with the to-css-custom-properties parser:

"parsers": [
  {
    "name": "to-css-custom-properties",
    "output": {
      "type": "file",
      "filePath": "style.css"
    }
  }
]

Directory

Use case: the parser is expected to produce 0 to N files, all placed in the given base directory.

type DirectoryOutput = {
  type: 'directory';
  directoryPath: string;
}

Example with the to-svg-file parser:

"parsers": [
  {
    "name": "to-svg-file",
    "output": {
      "type": "directory",
      "directoryPath": "./public/assets"
    }
  }
]