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
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
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.
BuiltInParserRuleConfiguration
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
}
The object is composed of the following properties:
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
false
The output you want the parser to generate. In most cases, a file
or a directory
.
ParsersEngineDataBox
ParsersEngineDataBox
The parsers engine can take several input types called parsers engine data boxes. On start, the Parsers engine requires one of the data box types to be passed in as initial input.
SDTF
type SDTFDataBox = {
type: "SDTF";
graph: SpecifyDesignTokenFormat;
metadata?:
| {
activeViewName: string | null;
views: Array<{
name: string;
query: SDTFQuery;
}>;
}
| undefined;
};
SDTF Engine
type SDTFEngineDataBox = {
type: "SDTF Engine";
engine: SDTFEngine;
}
Specify Repository
type SpecifyRepositoryDataBox = {
type: "repository";
owner: string;
name: string;
}
JSON
type JSONDataBox = {
type: "JSON";
json: string | number | boolean | unknown[] | Record<string, unknown> | null;
}
Vector
type VectorDataBox = {
type: 'vector';
format: 'svg' | 'pdf';
provider: 'external' | 'Specify';
extension: {
vector?: string, // The text representation of the SVG file
},
}
Bitmap
type BitmapDataBox = {
type: 'bitmap';
format: 'png' | 'wp2' | 'avif' | 'webp' | 'jpg' | 'jxl';
provider: 'external' | 'Specify';
extension: {
bitmap?: Array<number>, // The array buffer representation of the bitmap file
},
}
Asset
type AssetDataBox = {
type: 'asset';
format: 'png' | 'wp2' | 'avif' | 'webp' | 'jpg' | 'jxl' | 'svg' | 'pdf' | 'ttf' | 'woff' | 'woff2' | 'otf' | 'eot';
provider: 'external' | 'Specify' | 'Google Fonts' | 'Adobe Fonts';
}
ParserOutput
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"
}
}
]
Last updated
Was this helpful?