Do not register the plugin automatically (#24)

This is a breaking change for all projects since, for consistency,
this applies to all types of import (i.e. script, require, import).

Author: LeeLenaleee

README.md

@@ -11,7 +11,7 @@ Requires [Chart.js](https://github.com/chartjs/Chart.js/releases) **3.x**.
 ## Documentation
 
 - [Introduction](https://chartjs-plugin-deferred.netlify.app/)
-- [Installation](https://chartjs-plugin-deferred.netlify.app/installation.html)
+- [Getting Started](https://chartjs-plugin-deferred.netlify.app/getting-started.html)
 - [Options](https://chartjs-plugin-deferred.netlify.app/options.html)
 - [Samples](https://chartjs-plugin-deferred.netlify.app/samples/)
 

docs/.vuepress/config.js

@@ -90,8 +90,9 @@ module.exports = {
     sidebar: {
       '/guide/': [
         '',
-        'installation',
+        'getting-started',
         'options',
+        'migration'
       ],
       '/samples/': [
         'delay.md',

docs/guide/README.md

@@ -12,7 +12,7 @@ Requires [Chart.js](https://github.com/chartjs/Chart.js/releases) **3.x**
 
 ## Table of Contents
 
-* [Installation](installation.md)
+* [Getting Started](getting-started.md)
 * [Options](options.md)
 * [Samples](../samples)
 

docs/guide/installation.md docs/guide/getting-started.mddocs/guide/installation.md renamed to docs/guide/getting-started.md

@@ -1,22 +1,24 @@
-# Installation
+# Getting Started
 
-## npm
+## Installation
+
+### npm
 
 [![npm](https://img.shields.io/npm/v/chartjs-plugin-deferred.svg?style=flat-square&maxAge=600)](https://npmjs.com/package/chartjs-plugin-deferred) [![npm downloads](https://img.shields.io/npm/dm/chartjs-plugin-deferred.svg?style=flat-square&maxAge=600)](https://npmjs.com/package/chartjs-plugin-deferred)
 
 ```sh
 npm install chartjs-plugin-deferred --save
 ```
 
-## Bower
+### Bower
 
 [![bower](https://img.shields.io/bower/v/chartjs-plugin-deferred.svg?style=flat-square&maxAge=600)](https://libraries.io/bower/chartjs-plugin-deferred)
 
 ```sh
 bower install chartjs-plugin-deferred --save
 ```
 
-## CDN
+### CDN
 
 [![jsdelivr](https://img.shields.io/npm/v/chartjs-plugin-deferred.svg?label=jsdelivr&style=flat-square&maxAge=600)](https://cdn.jsdelivr.net/npm/chartjs-plugin-deferred@latest/dist/) [![jsdelivr hits](https://data.jsdelivr.com/v1/package/npm/chartjs-plugin-deferred/badge)](https://www.jsdelivr.com/package/npm/chartjs-plugin-deferred)
 
@@ -29,7 +31,7 @@ https://cdn.jsdelivr.net/npm/chartjs-plugin-deferred@1        // latest 1.x.x
 
 Read more about jsDeliver versioning on their [website](https://www.jsdelivr.com/).
 
-## Download
+### Download
 
 [![github](https://img.shields.io/github/release/chartjs/chartjs-plugin-deferred.svg?style=flat-square&maxAge=600)](https://github.com/chartjs/chartjs-plugin-deferred/releases/latest) [![github downloads](https://img.shields.io/github/downloads/chartjs/chartjs-plugin-deferred/total.svg?style=flat-square&maxAge=600)](https://somsubhra.github.io/github-release-stats/?username=chartjs&repository=chartjs-plugin-deferred)
 
@@ -40,3 +42,51 @@ You can download the latest version of `chartjs-plugin-deferred` from the [GitHu
 - `chartjs-plugin-deferred.esm.js`
 - `chartjs-plugin-deferred.tgz` (contains all builds)
 - `chartjs-plugin-deferred.zip` (contains all builds)
+
+## Integration
+
+### HTML
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/chart.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/chartjs-plugin-deferred.min.js">
+```
+
+::: warning IMPORTANT
+`chartjs-plugin-deferred` must be loaded **after** the Chart.js library!
+:::
+
+Once loaded, the plugin, available under the global `ChartDeferred` property, needs to be [registered](#registration).
+
+### Module
+
+```javascript
+import {Chart} from 'chart.js';
+import ChartDeferred from 'chartjs-plugin-deferred';
+```
+
+## Registration
+
+Since version 2.x, this plugin **no longer registers itself automatically**. It must be manually registered either globally or locally.
+
+```javascript
+// Register the plugin to all charts:
+Chart.register(ChartDeferred);
+```
+
+```javascript
+// OR only to specific charts:
+var chart = new Chart(ctx, {
+  plugins: [ChartDeferred],
+  options: {
+    // ...
+  }
+})
+```
+
+::: tip
+When imported via a [`<script>` tag](#html), use the global property `ChartDeferred`.
+:::
+
+See also [Chart.js &rsaquo; Using plugins](https://www.chartjs.org/docs/latest/developers/plugins.html).
+

docs/guide/migration.md

@@ -0,0 +1,53 @@
+# Migration
+
+## Migrating to v2.0.0
+
+### Breaking Changes
+
+Make sure to also read the [Chart.js v3 migration guide](https://www.chartjs.org/docs/latest/getting-started/v3-migration.html) since you may be impacted by more general breaking changes due to this new Chart.js version.
+
+#### Explicit Plugin Registration
+
+As described in the [getting started](getting-started.md#integration), it's now required to manually register this plugin, either globally:
+
+```js
+Chart.plugins.register(ChartDeferred);
+```
+
+or locally:
+
+```js
+new Chart('foo', {
+  plugins: [ChartDeferred]
+})
+```
+
+#### Plugin registration
+
+Chart.js v3 changed the way to register plugins and now requires to use `Chart.register(plugin)` instead of `Chart.plugins.register(plugin)`.
+
+```js
+import {Chart} from 'chart.js';
+import ChartDeferred from 'chartjs-plugin-deferred';
+
+Chart.register(ChartDeferred);
+```
+
+See [Getting Started > Registration](getting-started.html#registration) for details.
+
+#### Default options
+
+The plugin default options are now accessible in `Chart.defaults.plugins.deferred.*` instead of `Chart.defaults.global.plugins.deferred.*` and can be modified using:
+
+```js
+Chart.defaults.set('plugins.deferred', {
+  delay: 100,
+  // ...
+})
+```
+
+### Notes
+
+#### Chart.js type declaration <Badge text="TS only"/>
+
+Chart.js v3 now provides TypeScript type declaration files bundled in the npm package so it's **not** anymore required to install the `@types/chart.js` package.

rollup.config.js

@@ -13,6 +13,7 @@ module.exports = [
     input: 'src/plugin.js',
     output: ['.js', '.min.js'].map((suffix) => {
       const config = {
+        name: 'ChartDeferred',
         file: `dist/${pkg.name}${suffix}`,
         banner: banner,
         format: 'umd',

src/plugin.js

@@ -120,7 +120,7 @@ function unwatch(chart) {
   chart[MODEL_KEY].elements = [];
 }
 
-Chart.register({
+export default {
   id: 'deferred',
 
   defaults: {
@@ -180,4 +180,4 @@ Chart.register({
   destroy: function(chart) {
     unwatch(chart);
   }
-});
+};