Format output aggregation

[TrevorRice]

Hi all!

I'm curious if anyone has found an easy way to aggregate all platform outputs into a single object. For documentation purposes, I'd love to be able to construct an object similar to the one below to quickly iterate over and display in a filterable table:

[
  {
    name: "token-1",
    ... // some documentation-specific metadata (version added, etc.)
    platforms: {
      css: { name: "--token-1", value: "..." },
      scss: { name: "$token-1", value: "..." },
      swift: { ... },
      ...
    }
  },
  ...
]

Apologies if I'm completely overlooking something in the docs.

[jorenbroekema]

https://styledictionary.com/reference/api/#formatallplatforms this should come in handy

import StyleDictionary from 'style-dictionary';

StyleDictionary.registerFormat({
   name: 'js-memory',
   format: ({ dictionary }) => dictionary.allTokens,
 })

const sd = new StyleDictionary({
  platforms: {
    css: {
      transformGroup: 'css',
      files: [{
        format: 'js-memory' // use this one for all your platforms
      }]
    }
  }
});

/**
 * this is the magic
 * Output will look something like:
 * {
 *   css: [
 *     { 
 *       output: [{ 
 *         name: 'token-1',
 *         value: '...'
 *       }] 
 *     }  
 *   ]
 * }
 *
 */
const platformOutputs = await sd.formatAllPlatforms();

const tokens = [];
Object.entries(platformOutputs).forEach(([platKey, files], index) => {
  files[0].output.forEach(outputToken => {
    // first time encountering this token, construct it in the array
    if (index === 0) {
      tokens.push({
        name: outputToken.name,
        platforms: {}
      });
    }

    const token = tokens.find(t => t.name === outputToken.name);
    token.platforms[platKey] = {
      name: convertNameToCSSProp(token.name),
      value: outputToken.value,
    }
  })
});

I wrote this code from scratch here inside the Github reply so no guarantees this runs/compiles but this is the rough approach to it:

• use the formatPlatform / formatAllPlatforms method in combination with a custom format that just returns the allTokens array to JS memory, so it doesn't actually output to files (e.g. .css file etc.)
• aggregate all of the outputs into a single array structure by looping over the platform outputs and within those looping over the tokens array

You will still need some kind of utils to convert the token name to the naming conventions (e.g. CSS custom props, SCSS props) of your choosing though. And every platform in your config must use the same name transform, judging by your post that would be name/kebab, if they use different ones then they won't be correctly aggregated in the same array item, since the name is what you are using as the item identifier.

FYI it might be easier to use a "name"-keyed object / Map() instead of a name-keyed array, would be easier to access, less need for Array.find()

[TrevorRice]

This is great, thanks, @jorenbroekema! Since Style Dictionary itself converts token names into their appropriate platform-specific format, do you see a future opportunity to expose those as part of style-dictionary/utils?

[jorenbroekema]

You can kind of access those already by doing StyleDictionary.hooks.transforms['name/kebab'].transform(token) => outputs the transformed token name.

So in a sense they're already exposed, all of the built-in hooks of StyleDictionary are, on the hooks prop on the module. I think this is fine but perhaps needs better documentation.

The utils entrypoint could potentially also make for a good place to expose them though, I do agree with that, or maybe we'd have a style-dictionary/transforms and /formats entrypoints for exposing just the transform and format functions (without their filters, name, and other sibling props like that?). I'm just not really sure how big the benefits of that are and if it's worth it to maintain extra entrypoints for our built-ins.
I low-key feel like this would be great for a plugin/integration package with Style Dictionary like sd-transforms or style-dictionary-utils to maintain these kinds of things. I would love it for example if someone came out with an iOS / Android integration package for Style Dictionary with a ton of transforms/formats for those mobile platforms, as the built-ins in Style Dictionary are admittedly not the best.