Custom Formatters File and Tree Shaking

Product/Library Releases & New Features SDK/Theme Updates
,
1

Theme 1.17 introduces more formalized tree shaking (a form of dead code elimination) to help with page speed.

With this version of the theme, there are 3 formatter files:

  • Formatter.js - list of formatters that will be used
  • Formatters-internal.js - list of theme formatter definitions
  • Formatters-custom.js - for custom formatters and formatter changes. Newly added with theme 1.17.

How to Update an Existing Formatter

Fork formatters-custom.js, copy over the formatter from formatters-internal.js and edit it as needed. So long as you use the same name, we’ll pick your custom one.

How to Create a New Formatter

Fork formatters-custom.js and define it there. (You don’t need to list it in imports and exports, since we include all formatters from formatters-custom.js by default.)

Tree Shaking :evergreen_tree:

  1. Shadow formatters.js
  2. Confirm that the formatter is not being used in any of the cards you’re referencing
  3. Comment it out in both the import and export statement in formatters.js

Upgrade Implications

We’ve made a couple of changes to formatters across the past few theme releases, so documenting them all here. The TL;DR is if you did special things with your formatters previously, they should not break when you upgrade to this version, but we’d recommend updating your formatter file pattern to match the most recent outlined above.

Upgrading to 1.17 from 1.13 or Older (Has formatters.js)

  • If you haven’t forked your formatter.js file: do nothing, and follow the above instructions.
  • If you previously forked your formatter.js file to either add a new formatter, remove a formatter or change an existing formatter: Do nothing, this will continue to work. .

Upgrading to 1.17 from 1.14, 1.15 or 1.16 (Has formatters.js and formatters-internal.js)

  • If you previously updated an existing formatter by forking formatters-internal.js and updating it there, this will continue to work.
  • If you previously created a new formatter by forking formatters-internal and defining it there, then listing in imports/exports in formatters.js, that will also continue to work. Moving forward, you can define your custom formatters in formatters-custom.js.