Style-dictionary: Add header to all formats

[lukasoppermann]

Hey @dbanksdesign, I am trying to get the style-dictionary to work with the design token spec idea outlined by the w3c community group: https://github.com/design-tokens/community-group/issues/1

Getting the tokens out works fine in a custom build file like this

const StyleDictionaryExtended = require('style-dictionary').extend(__dirname + '/config.json');
const {tokens, version, data} = require(__dirname + '/tokens/w3c-design-tokens.json')
console.log('Build started...');
console.log('\n==============================================');
// turning array into a style-dictionary compatible object
StyleDictionaryExtended.properties = tokens.reduce((acc, item) => ({
  ...acc, [item.name]: item
}), {})

However, I would love to add the version and maybe some meta data from the data constants to the header of every transformed output. It seems to be quite cumbersome to create a custom format with StyleDictionaryExtended.registerFormat for every language (sass, json, ios, android) just to add a header.

So I was wondering, is there a way to add some content to the header for all files?

[brianespinosa]

@lukasoppermann I had to dig a little to do the same thing. The only way I could accomplish this was with StyleDictionary.formatHelpers and making a custom format. I think this might also only be possible in the next branch for 3.0.0

Take a look at Formats and format helpers.

[lukasoppermann]

Hey @brianespinosa, this is great.

Since I am using this for a tool that others use, I can't really recommend an unreleased version though. 😢

@dbanksdesign I take it there is no way of "releasing" this feature before version 3.0.0 because it probably requires the new structure, etc, correct?

[dbanksdesign]

@lukasoppermann that is correct. But we should be releasing 3.0.0 pretty soon, just a few more things to finish up. Adding custom data into the header of formats might be cool idea if there is a way we can do it in a generic and flexible way.

[lukasoppermann]

Hey @dbanksdesign that sounds great. I wasn't sure how long it will take until the release (as I know form my own project that OS is always quite a lot of work).

I would think allowing users to extend the fileHeader function could be a great way. Maybe by adding an array of lines (or a function that returns an array of lines) and those lines will be added to the header?

E.g. in the build.js file

// usage
StyleDictionary.formatHelpers.fileHeader.extend([
`Version: ${version}`,
`Some other org specific info`
])

// Would result in (style = short)

// Do not edit directly\n';
// Generated on dd.mm.yyyy
// Version: 2.3.12
// Some other org specific info

I don't know if this is a stupid idea as I just quickly dove into the code. But it would be great if one could overwrite or extend the fileHeader once in build.js and it would be used for all formats (without a need to overwrite all the formats).

Does this make sense?

[nhoizey]

This is a great idea! 👍

It reminds me of https://github.com/amzn/style-dictionary/issues/388#issuecomment-786816256

[lukasoppermann]

Hey @nhoizey, that is definitely were it comes from. The only difference I would love to see, is that we don't have to define a new format for all languages. In my projects I sometimes have to support 4 or more languages. If you have to maintain 4+ separated format extensions it is easy to forget something or introduce errors to one of the formats.

Also, if I only want to change the header, it seems wrong to have to define the entire workflow of the format again.

[nhoizey]

I would definitely welcome a way to add a header to all formats without any new format definition! 👍

[brianespinosa]

@lukasoppermann I love the proposal. I think the only thing I would suggest is if extend exposes the default message so you could use it how you like.

// usage
StyleDictionary.formatHelpers.fileHeader(true, 'short').extend(({defaultMessage}) => {
  return [
    `Version: ${version}`,
    `Some other org specific info`,
    ...defaultMessage,
  ])
)

// Version: 2.3.12
// Some other org specific info
// Do not edit directly\n';
// Generated on dd.mm.yyyy

[lukasoppermann]

@brianespinosa Either this or it just overwrites all lines, so you can & have to add the default message back, if you want it in there.

However if the default message gets more Infos like suggested in #388 exposing the default message would be great

[chazzmoney]

@dbanksdesign can't we just do it the way we do everything else? Allow registration of formatHelpers / via extend?

[dbanksdesign]

Great idea @chazzmoney! And everyone on this thread!

[nhoizey]

@dbanksdesign I just tried this new feature, it's great! 👍

[dbanksdesign]

This is now in the latest RC build, 3.0.0-rc.7, which you can get with npm install style-dictionary@next Let me know what you think!