A build system for creating cross-platform styles.
6cc7f31: BREAKING:
usesReference
util function is now usesReferences
to be consistent plural form like the other reference util functions.
getReferences
first and second parameters have been swapped to be consistent with resolveReferences
, so value first, then the full token object (instead of the entire dictionary instance).
getReferences
accepts a third options parameter which can be used to set reference Regex options as well as an unfilteredTokens object which can be used as a fallback when references are made to tokens that have been filtered out. There will be warnings logged for this.
format.formatter
removed old function signature of (dictionary, platform, file)
in favor of ({ dictionary, platform, options, file })
.
Types changes:
.d.ts
files published next to every file, this means that if you import from one of Style Dictionary's entrypoints, you automatically get the types implicitly with it. This is a big win for people using TypeScript, as the majority of the codebase now has much better types, with much fewer any
s.index.d.ts
anymore that exposes all type interfaces on itself. This means that you can no longer grab types that aren't members of the Style Dictionary class directly from the default export of the main entrypoint. External types such as Parser
, Transform
, DesignTokens
, etc. can be imported from the newly added types entrypoint:import type { DesignTokens, Transform, Parser } from 'style-dictionary/types';
Please raise an issue if you find anything missing or suddenly broken.
Matcher
, Transformer
, Formatter
, etc. are still available, although no longer directly but rather as properties on their parents, so Filter['matcher']
, Transform['transformer']
, Format['formatter']
122c8f6: Expose a new utility called resolveReferences which takes a value containing references, the dictionary object, and resolves the value's references for you.
import StyleDictionary from 'style-dictionary';
import { resolveReferences } from 'style-dictionary/utils';
const sd = new StyleDictionary({
tokens: {
foo: { value: 'foo' },
bar: { value: '{foo}' },
qux: { value: '{bar}' },
},
});
console.log(resolveReferences(sd.tokens.qux.value, sd.tokens)); // 'foo'
122c8f6: BREAKING: expose getReferences and usesReference utilities as standalone utils rather than requiring them to be bound to dictionary object. This makes it easier to use.
a4542f4: BREAKING: StyleDictionaryInstance.properties & .allProperties have been removed. They were deprecated in v3 in favor of .tokens and .allTokens.
a4542f4: BREAKING: StyleDictionary to be initialized with a new API and have async methods. Use:
import StyleDictionary from 'style-dictionary';
/**
* old:
* const sd = StyleDictionary.extend({ source: ['tokens.json'], platforms: {} });
* sd.buildAllPlatforms();
*/
const sd = new StyleDictionary({ source: ['tokens.json'], platforms: {} });
await sd.buildAllPlatforms();
You can still extend a dictionary instance with an extended config, but .extend()
is only used for this, it is no longer used to initialize the first instance:
import StyleDictionary from 'style-dictionary';
const sd = new StyleDictionary({ source: ['tokens.json'], platforms: {} });
const extended = await sd.extend({
fileHeader: {
myFileHeader: (defaultMessage) => {
return [...defaultMessage, 'hello, world!'];
},
},
});
To ensure your initialized StyleDictionary instance is fully ready and has imported all your tokens, you can await hasInitialized
:
import StyleDictionary from 'style-dictionary';
const sd = new StyleDictionary({ source: ['tokens.json'], platforms: {} });
await sd.hasInitialized;
console.log(sd.allTokens);
For error handling and testing purposes, you can also manually initialize the style-dictionary config:
import StyleDictionary from 'style-dictionary';
const sd = new StyleDictionary({ source: ['tokens.js'], platforms: {} }, { init: false });
try {
await sd.init();
} catch (e) {
// handle error, e.g. when tokens.js file has syntax errors and cannot be imported
}
console.log(sd.allTokens);
The main reason for an initialize step after class instantiation is that async constructors are not a thing in JavaScript, and if you return a promise from a constructor to "hack it", TypeScript will eventually trip over it.
Due to being able to dynamically (asynchronously) import ES Modules rather than synchronously require CommonJS modules, we had to make the APIs asynchronous, so the following methods are now async:
In a future release, most other methods will be made async or support async as well, such as parsers, transforms, formats etc.
c1dd5ec: Allow overriding CSS formatting with commentStyle and commentPosition props. For commentStyle, options are 'short' or 'long'. For commentPosition, options are 'above' or 'inline'.
We also ensure that the right defaults are picked for CSS, SASS/SCSS, Stylus and Less.
This also contains a fix for ensuring that multi-line comments are automatically put "above" rather than "inline".
6fb81ad: Allow falsy token values for outputReferences, e.g. 0
.
24d41c3: Allow outputReferences to work on non-string values.
Style-Dictionary.extend()
method is now asynchronous, which means it returns Promise<StyleDictionary.Core>
instead of StyleDictionary.Core
.allProperties
/ properties
was deprecated in v3, and is now removed from StyleDictionary.Core
, use allTokens
and tokens
instead.registerTemplate
were deprecated in v3, now removed. Use Formats instead.style-dictionary
& style-dictionary/fs
. If more is needed, please raise an issue explaining which file you were importing and why you need it to be public API.dcbe2fb: FileSystem that is used by Style-Dictionary can now be customized:
import { setFs } from 'style-dictionary/fs';
setFs(myFileSystemShim);
By default, it uses an in-memory filesystem shim @bundled-es-modules/memfs
in browser context, node:fs
built-in module in Node context.
All notable changes to this project will be documented in this file. See standard-version for commit guidelines.
options.import
at compose/object by @lucoel in https://github.com/amzn/style-dictionary/pull/958
Full Changelog: https://github.com/amzn/style-dictionary/compare/v3.7.2...v3.8.0
Full Changelog: https://github.com/amzn/style-dictionary/compare/v3.7.1...v3.7.2
Full Changelog: https://github.com/amzn/style-dictionary/compare/v3.7.0...v3.7.1
removePrivate
by @silversonicaxel in https://github.com/amzn/style-dictionary/pull/770
Core.format
by @jakobe in https://github.com/amzn/style-dictionary/pull/780
Full Changelog: https://github.com/amzn/style-dictionary/compare/v3.1.1...v3.7.0