amzn/style-dictionary

# Formats

Formats define the output of your created files. For example, to use your styles in CSS
you use the `css/variables` format. This will create a CSS file containing the variables from
your style dictionary.

### Using formats

You use formats in your config file under platforms > [platform] > files > [file] > format

```json
{
  "source": ["properties/**/*.json"],
  "platforms": {
    "css": {
      "transformGroup": "css",
      "files": [
        {
          "format": "css/variables",
          "destination": "variables.css"
        }
      ]
    }
  }
}
```

There is an extensive (but not exhaustive) list of [included formats](#pre-defined-formats) available in Style Dictionary.

### Format configuration

Formats can take configuration to make them more flexible. This allows you to re-use the same format multiple times with different configurations or to allow the format to use data not defined in the tokens themselves. To configure a format, add extra attributes on the file object in your configuration like the following:

```json
{
  "source": ["properties/**/*.json"],
  "platforms": {
    "scss": {
      "transformGroup": "scss",
      "files": [{
        "destination": "map.scss",
        "format": "scss/map-deep",
        "mapName": "my-tokens"
      }]
    }
  }
}
```

In this example we are adding the `mapName` configuration to the `scss/map-deep` format. This will change the name of the SCSS map in the output. Not all formats have the configuration options; format configuration is defined by the format itself. To see the configurtion options of a format, take a look at the documentation of the [specific format](#pre-defined-formats)

### Filtering tokens

A special file configuration is `filter`, which will filter the tokens before they get to the format. This allows you to re-use the same format to generate multiple files with different sets of tokens. Filtering tokens works by adding a `filter` attribute on the file object, where `filter` is:

* An object which gets passed to [Lodash's filter method](https://lodash.com/docs/4.17.14#filter).
* A string that references the name of a registered filter, using the [`registerFilter`](api.md#registerfilter) method
* A function if you are defining your configuration in Javascript rather than JSON. The filter function takes a token as the property and should return a boolean if the token should be included (true) or excluded (false).

```javascript
{
  "destination": "destination",
  "format": "myCustomFormat",
  "filter": "myCustomFilter", // a named filter defined with .registerFilter
  "filter": function(token) {}, // an inline function
  "filter": {} // an object pass to lodash's filter method
}
```

### Creating formats

You can create custom formats using the [`registerFormat`](api.md#registerformat) function. If you want to add configuration to your custom format, `this` is bound to the file object. Using this, you can access attributes on the file object with `this.myCustomAttribute` if the file object looks like:

```json
{
  "destination": "destination",
  "format": "myCustomFormat",
  "myCustomAttribute": "Hello world"
}
```


### Using a template / templating engine to create a format

Formatters are functions and created easily with most templating engines. Formats can be built using templates if there is a lot of boilerplate code to insert (e.g. ObjectiveC files). If the output consists of only the values (e.g. a flat SCSS variables file), writing a formatter function directly may be easier.

Any templating language can work as there is a node module for it. All you need to do is register a format that calls your template and returns a string.

Here is a quick example for Lodash.

```js
const styleDictionary = require('style-dictionary').extend('config.json');
const _ = require('lodash');

const template = _.template( fs.readFileSync('templates/myFormat.template') );

styleDictionary.registerFormat({
  name: 'my/format',
  formatter: template
});

// format: 'my/format' is now available for use...
```

And another example for Handlebars.

```js
const styleDictionary = require('style-dictionary').extend('config.json');
const Handlebars = require('handlebars');

const template = Handlebars.compile( fs.readFileSync('templates/MyTemplate.hbs').toString() );

styleDictionary.registerFormat({
  name: 'my/format',
  formatter: function(dictionary, platform) {
    return template({
      properties: dictionary.properties,
      options: platform
    });
  }
});

// format: 'my/format' is now available for use...
```

----

## Pre-defined Formats

These are the formats included in Style Dictionary by default, pulled from [lib/common/formats.js](https://github.com/amzn/style-dictionary/blob/master/lib/common/formats.js)

Want a format? [You can request it here](https://github.com/amzn/style-dictionary/issues).

You created a format and think it should be included? [Send us a PR](https://github.com/amzn/style-dictionary/pulls).


{{#namespace name="Formats"}}{{>members~}}{{/namespace}}