Propose a simplified registration process

[etimberg]

Background

Starting in V3, we moved ESM builds to require registration of elements, controllers, plugins, and scales. This enables bundlers such as webpack to remove unused code from the build. However, forcing users to deal with this problem caused a number of headaches.

Proposal

This PR separates tree-shaking into a separate sub-package, chart.js/tree. When users import from this location, they are required to register the elements they are using. If the user imports from chart.js, they can use a default import that has all of the necessary pieces pre-registered.

Testing

I conducted local testing using a separate app available at https://github.com/etimberg/chartjs-tree-shaking-test
I tested imports from both chart.js and chart.js/tree. I confirmed that tree-shaking took place when using the chart.js/tree package + registration.

[etimberg]

I tested this out locally with https://github.com/etimberg/chartjs-tree-shaking-test and was able to see the benefits of tree-shaking when using the chart.js/tree package.

[simonbrunel]

Thanks @etimberg for looking at this :)

I think I would keep the regular chart.js import shakable and only provide shortcuts to register all the things:

import {
   Chart,
   controllers,
   elements,
   plugins,
   scales,
} from 'chart.js';

Chart.register(
    ...Object.values(controllers),
    ...Object.values(elements),
    ...Object.values(plugins),
    ...Object.values(scales),
);

// or

import { Chart, registrables } from 'chart.js';

Chart.register(...registrables);

I'm not really sure we need the auto-register (none shakable) version because users could directly use the UMD build instead. In the case of the datalabels docs, I can definitely live with one version above, else I would use the UMD build. If you think we should provide an ESM build for this use case (auto-register), then I would make it the special case (i.e. import 'chart.js/auto' or whatever name).

[simonbrunel]

Is it really working? I can't find were you export these groups.

[etimberg]

No, I forgot to delete that part of the docs when I switched around how this worked.

[simonbrunel]

Out of the scope of this PR: could this be moved under a single folder and copied when publishing to npm? For example: ./esm/helpers, ./esm/tree, etc. (or a different folder name).

[etimberg]

I think NPM in that case might consider the package to be chart.js/dist/helpers but we'd have to experiment and see

[simonbrunel]

These extra packages could even be generated by a script as we did with bowser.json

[simonbrunel]

I think users expect the default behavior (i.e. import {...} from 'chart.js') to be tree-shakable, which may be the most common use case. It's also the natural method to import from Chart.js and it may be better to keep it that way. As a plugin developers, I would also expect the following snippet to only bring LineElement and not trigger any auto-registration:

import { LineElement } from 'chart.js';

export class CurveElement extends LineElement {
  // ...
}

It may be better to have a special case for auto-registering instead (e.g. chart.js/auto or chart.js/all).

[simonbrunel]

I don't think you need to wrap everything in an array:

Chart.register(
    ...Object.values(controllers),
    ...Object.values(elements),
    ...Object.values(plugins),
    ...Object.values(scales),
);

[simonbrunel]

We could make this even easier by exporting an array containing everything:

import { registrables } from 'chart.js';

Chart.register(...registrables);

You might have a better name for registrables.

[simonbrunel]

You still need to export those groups:

// ...
export * from './plugins';
export * from './scales';

// Exporting groups to simplify the registration.
export * as controllers from './controllers';
export * as elements from './elements';
export * as plugins from './plugins';
export * as scales from './scales';

[etimberg]

So I tested the single package version locally and it works for tree shaking as well.

index.esm.js

export * from './controllers';
export * from './core';
export * from './elements';
export * from './platform';
export * from './plugins';
export * from './scales';

export * as controllers from './controllers';
export * as elements from './elements';
export * as plugins from './plugins';
export * as scales from './scales';

In the test project, to register all

import Chart, { controllers, elements, plugins, scales } from 'chart.js';
Chart.register(controllers, elements, plugins, scales);

In the test project to register some

import {
  Chart,
  LineElement,
  PointElement,
  LineController,
  CategoryScale,
  LinearScale,
  Legend,
  Tooltip
} from 'chart.js';

Chart.register(
  LineElement, PointElement, LineController,
  CategoryScale, LinearScale,
  Legend, Tooltip,
)

The outcome of this is the same as before. 164kB for the all version and 155kB for the tree-shaken version.

@kurkle since the separate package was your idea, any opinions?

Edit:
I also tested the registerables version

export const registerables = [
  ...Object.values(controllers),
  ...Object.values(elements),
  ...Object.values(plugins),
  ...Object.values(scales),
];

It did not tree-shake correctly because the registerables array was not marked as /*#__PURE__*/ by webpack.

If I change the export to

export const registerables = [
  controllers,
  elements,
  plugins,
  scales,
];

it works, but now the user must do Chart.register(...registerables).

[simonbrunel]

It did not tree-shake correctly because the registerables array was not marked as /#PURE/ by webpack.

I think it works if you don't use Object.values() but instead create a src/registrables.js file exporting each import:

// src/registrables.js`
import { BarController, LineController, ... } from './controllers';
import { LineElement, PointElement,, ... } from './elements';
// ... all other registrables imports

export const registrables: [
  BarController,
  LineController,
  LineElement,
  PointElement,
  // ...
];

// src/index.esm.js
export * from './registrables.js';

[etimberg]

Yup, removing Object.values should fix it. Locally I preferred the array containing the maps directly, i.e. registerables = [controllers, elements, plugins, scales]; so that it leaves one less place to modify if we ever add a new plugin, controller, etc.

[simonbrunel]

Though, I'm not against the separate package, however I don't think the chart.js import should auto-register everything (as explained in a previous comment). If we decide to add this separate package, I would still export groups of imports (i.e. controller, elements, etc.) but not the registrables array which may be useless in this case.

[etimberg]

Now that I have proof the single package works, it's probably easier since there's less to maintain and the diff is a lot smaller. So I'd propose we go back to requiring registration, export groups & a single registerables list to provide some flexibility. I put up those changes in #8425

[kurkle]

just commenting the registables, I think this should work:
export Object.assign({}, controllers, scales, elements, plugins)

[etimberg]

Closing in favour of #8425