diff --git a/.changeset/pre.json b/.changeset/pre.json index b2c3f8215..f45614819 100644 --- a/.changeset/pre.json +++ b/.changeset/pre.json @@ -8,7 +8,11 @@ "big-worms-collect-2", "big-worms-collect", "bright-timers-shout", + "fifty-dragons-heal", + "gorgeous-lamps-chew", "honest-toes-wink", - "nice-ears-shop" + "light-games-occur", + "nice-ears-shop", + "unlucky-cameras-draw" ] } diff --git a/CHANGELOG.md b/CHANGELOG.md index fcc1521cd..41ed7604e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,80 @@ # Changelog +## 4.0.0-prerelease.2 + +### Major Changes + +- 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: + + ```js + 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: + + ```js + 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`: + + ```js + 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: + + ```js + 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: + + - extend + - exportPlatform + - buildAllPlatforms & buildPlatform + - cleanAllPlatforms & cleanPlatform + + In a future release, most other methods will be made async or support async as well, such as parsers, transforms, formats etc. + +### Minor Changes + +- cedf8a0: Preprocessors are a new feature added to style-dictionary, which allows you to do any type of processing of the token dictionary **after** parsing, **before** resolving and transforming. + See [preprocessor docs](https://github.com/amzn/style-dictionary/tree/v4/docs/preprocessors.md) for more information. +- a4542f4: options.log to be respected in all error logging, including platform specific logs. + ## 4.0.0-prerelease.1 ### Patch Changes diff --git a/package.json b/package.json index 08dec5f08..44ba26bf6 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "style-dictionary", - "version": "4.0.0-prerelease.1", + "version": "4.0.0-prerelease.2", "description": "Style once, use everywhere. A build system for creating cross-platform styles.", "keywords": [ "style dictionary",