Getting Started With Tree Shaking

Tree shaking lets you create custom ChartIQ bundles by including only the features your application needs. By excluding unused features, you reduce bundle size and improve load-time performance.

Quick Start

In chartiq/webpack-example/, you will find the following files:

• importActivation.js — Standard features
• importActivationAdvanced.js — Advanced features

Comment out or delete the features you don't need; when you build your bundle for production using webpack (npm run build), any features you don't activate in the CIQ.activateImports() call will be excluded from your bundle.

How It Works

ChartIQ uses two complementary techniques to enable tree shaking: a consistent activation mechanism via CIQ.activateImports(), and a build-time configuration flag called __TREE_SHAKE__.

CIQ.activateImports()

CIQ.activateImports() provides a consistent way to specify which modules your application needs. Each tree-shakable library module exports a wrapper function that initializes the module. When you call CIQ.activateImports() with specific exports, you explicitly invoke those wrapper functions.

The four tree-shakable library files (standard.js, advanced.js, components.js, and addOns.js) each contain a conditional check that controls automatic export activation based on the __TREE_SHAKE__ setting.

Technically, you don't have to use CIQ.activateImports(); you could manually invoke the wrapper functions yourself. However, if you don't use this function, you become responsible for:

• Keeping track of which modules have already had their wrapper functions invoked
• Ensuring wrapper functions aren't called more than once
• Avoiding accidental duplicate initialization

Any module whose wrapper function is not called is treated as dead code and becomes a candidate for removal from the final bundle during the build process.

You can think of the CIQ.activateImports() function as a module initialization mechanism, similar to calling an initialize() method for each module you need. Since the library modules are now implemented as functions, they won't initialize unless those functions are invoked.

Example from importActivation.js:

if (typeof __TREE_SHAKE__ !== "undefined" && __TREE_SHAKE__) {
  /* comment out any feature you do not want in your bundle */
  CIQ.activateImports(
    Standard.createEngine,
    // AddOns.fullScreen,     // Excluded from bundle
    AddOns.inactivityTimer,
    AddOns.rangeSlider,
    AddOns.tooltip,
    // Components.advertisement, // Excluded from bundle
    // ... more features
  );
}

In this example, when __TREE_SHAKE__ is true (more on this below), only the listed exports are activated. The commented-out features, like AddOns.fullScreen and Components.advertisement, are never invoked, so their code becomes dead code and webpack removes them entirely from your bundle.

__TREE_SHAKE__

The __TREE_SHAKE__ variable, defined in webpack.config.js, is a convenience mechanism that allows existing users who don't use webpack or prefer not to change how their bundles are constructed to maintain full functionality without special configuration.

• If defined and true (webpack, production mode): Do not automatically activate everything. Let the user decide what to include via CIQ.activateImports().
  • __TREE_SHAKE__ is defined and true by default. See the example below for what is in webpack.config.js.
• If not defined or false (non-webpack users, or development mode): Automatically activate all wrapper functions internally so the user gets full functionality without extra work.

Example from webpack.config.js:

new webpack.DefinePlugin({
  __TREE_SHAKE__: JSON.stringify(env === "production")
})

Together, these two mechanisms work in tandem: the __TREE_SHAKE__ flag controls whether modules auto-activate, while CIQ.activateImports() gives you explicit control over which modules to initialize. Tree shaking is simply the process of removing the code for modules you never initialize.

Summary

Tree shaking lets you optimize your ChartIQ bundle by including only the features your application uses. Comment out unneeded features in your importActivation.js file, and webpack removes them during the production build. This gives you control over bundle size while keeping the flexibility to add features back as needed.