ember-cli-bundle-analyzer

ember-cli-bundle-analyzer

An Ember CLI addon to analyze the size and contents of your app's bundled output, using an interactive zoomable treemap.

View the interactive Demo

This helps you to

• analyze which individual modules make it into your final bundle
• find out how big each contained module is
• find modules that got there by mistake
• optimize your bundle size

It uses source-map-explorer under the hood, and wraps it in an Ember CLI addon to make it easy to use.

Given that it works based on source maps, it is agnostic to the actual bundling tool used, be it pure Ember CLI (which is based on broccoli-concat), Ember CLI with ember-auto-import (which makes it a mix of broccoli-concat and webpack) or even Embroider. The only condition is that proper source maps are generated.

Compatibility

• Ember CLI v3.28 or above
• Node.js v16 or above
• works with ember-auto-import and Embroider, as long as source maps are properly enabled

Quick Start

To get you going quickly, follow these steps:

1. Install the addon:

   ember install ember-cli-bundle-analyzer
   

2. Setup your ember-cli-build.js:

   const EmberApp = require('ember-cli/lib/broccoli/ember-app');
   +const {
   +  createEmberCLIConfig,
   +} = require('ember-cli-bundle-analyzer/create-config');
   
   module.exports = function (defaults) {
     const app = new EmberApp(defaults, {
       // your other options are here
       // ...
   +    ...createEmberCLIConfig(),
     });
   
     return app.toTree();
   };
   

3. Launch your local server in analyze-mode:

   ENABLE_BUNDLE_ANALYZER=true ember serve --prod
   

4. Open http://localhost:4200/_analyze

For more detailed instructions, read the following chapters...

Setup

Two things need to be in place for this addon to work correctly: it needs to have a config that at least enables it, and proper source maps need to be enabled for the EmberCLI build pipeline.

While it is possible to provide these settings manually, the addon provides some recommended presets that you can apply using createEmberCLIConfig:

// ember-cli-build.js
const EmberApp = require('ember-cli/lib/broccoli/ember-app');
const {
  createEmberCLIConfig,
} = require('ember-cli-bundle-analyzer/create-config');

module.exports = function (defaults) {
  const app = new EmberApp(defaults, {
    // your other options are here
    // ...
    ...createEmberCLIConfig(),
  });

  return app.toTree();
};

If you are using Embroider, then this should cover you:

// ember-cli-build.js
const EmberApp = require('ember-cli/lib/broccoli/ember-app');
const {
  createEmberCLIConfig,
  createWebpackConfig,
} = require('ember-cli-bundle-analyzer/create-config');

module.exports = function (defaults) {
  const app = new EmberApp(defaults, {
    // your other options are here
    // ...
    ...createEmberCLIConfig(),
  });

  return require('@embroider/compat').compatBuild(app, Webpack, {
    // your Embroider options...
    packagerOptions: {
      webpackConfig: {
        // any custom webpack options you might have
        ...createWebpackConfig(),
      },
    },
  });
};

With this config, when the environment variable ENABLE_BUNDLE_ANALYZER is set, it will enable the addon and apply required options to both Ember CLI and ember-auto-import to fully enable source maps with the required fidelity level.

The reason the addon is not enabled by default is that it would be pointless if not having proper source maps fully enabled as well. And this might not be what you want by default, as generating full source maps comes at a cost of increased build times. On top of that you might also want to analyze the bundles only in production mode.

Note that this might override some of your existing custom settings for source maps or ember-auto-import if you have those. So if that does not work for you, you can either try to deep merge the configs as in the following example, or provide your own explicit configs based of what createEmberCLIConfig provides.

// ember-cli-build.js
const EmberApp = require('ember-cli/lib/broccoli/ember-app');
const {
  createEmberCLIConfig,
} = require('ember-cli-bundle-analyzer/create-config');
const { defaultsDeep } = require('ember-cli-lodash-subset');

module.exports = function (defaults) {
  const app = new EmberApp(
    defaults,
    defaultsDeep(
      {
        // your other options are here
        // ...
      },
      createEmberCLIConfig()
    )
  );

  return app.toTree();
};

Config

You can customize the precessing by setting any of the following configs into the 'bundleAnalyzer' key of your ember-cli-build.js:

• enabled (boolean): set to true to enable the addon. false by default.

• ignoreTestFiles (boolean): by default it will exclude all test files from the output. Set this to false to include them.

• ignore (string | string[]): add files to ignore. Glob patterns are supported, e.g. *-fastboot.js.

Source maps

The bundle size output that you see coming from this addon can only be as good as the underlying source maps are. For source-map-explorer to correctly process those, they should have the full source code included inline (which is the sourcesContent field in a .map file).

For the broccoli-concat based part of Ember CLI (processing the app itself as well as all v1 addons), enabling source maps using sourcemaps: { enabled: true }, in ember-cli-config.js will be enough. For any webpack based build (be it ember-auto-import or Embroider), the default settings will not be enough. The only setting that works reliably is enabling high-fidelity source maps using devtool: 'source-map'.

Again, for enabling source maps with the recommended options, using the createEmberCLIConfig() helper as mentioned above is recommended.

For further information consider these resources:

• Enabling source maps in Ember CLI
• Adding custom webpack config to ember-auto-import
• Adding custom webpack config to Embroider
• webpack's devtool

Usage

You need to have the addon and source maps enabled as described under Setup. When following the recommended approach of using createEmberCLIConfig to apply the addon provided presets, then opting into the bundle-analyzer enabled mode is done by enabling the ENABLE_BUNDLE_ANALYZER environment flag when starting your local dev server. Most likely you will also want to analyze the production mode build, to exclude any debugging code. So the final invocation would be:

ENABLE_BUNDLE_ANALYZER=true ember serve --prod

After startup this addon adds a custom middleware listening to the /_analyze URL path. So just open http://localhost:4200/_analyze in your web browser to access the analyzer output.

While it processes the data a loading screen might appear, after which the final output should display.

Live reloading is supported, so whenever you change a project file the output will be re-computed and updated automatically.

Contributing

See the Contributing guide for details.

License

This project is licensed under the MIT License.

Changelog

v1.0.0 (2023-02-08)

:boom: Breaking Change

• #26 Refactor to use source-map-explorer, enabling usage with Ember CLI, ember-auto-import and Embroider (@simonihmig)

:rocket: Enhancement

• #26 Refactor to use source-map-explorer, enabling usage with Ember CLI, ember-auto-import and Embroider (@simonihmig)

Committers: 1

• Simon Ihmig (@simonihmig)