Updating README.md

afarzat-ed · afarzat-ed · commit 06f2cf1a9ee6 · 2025-06-07T22:19:51.000-03:00
diff --git a/README.md b/README.md
@@ -49,10 +49,12 @@ import { CommonModule } from '@angular/common';
 import * as PlotlyJS from 'plotly.js-dist-min';
 import { PlotlyModule } from 'angular-plotly.js';
 
-PlotlyModule.plotlyjs = PlotlyJS;
 
 @NgModule({
-    imports: [CommonModule, PlotlyModule],
+    imports: [
+        CommonModule,
+        PlotlyModule.forRoot(PlotlyJS)
+    ],
     ...
 })
 export class AppModule { }
@@ -182,6 +184,107 @@ will put the user template into the root *\<div\>* of the resulting *plotly.js*
 in front of any plotly-generated elements. This could be useful for implementing plot overlays.
 
 
+## Customizing the `plotly.js` bundle
+
+By default, this library bundles `plotly.js` from the peer dependency together within the output. This results on huge outputs, for `plotly.js` itself is ~3MB when bundled. It also makes the build (with `ng serve --prod`) really slow, for it minifies everything together.
+
+If you wish to optimize loading `plotly.js` in a different way, please check both [`PlotlyViaCDNModule`](#plotly-via-cdn-module) and [`PlotlyViaWindowModule`](#plotly-via-window-module) modules below.
+
+
+### Plotly Via CDN Module
+
+If you want to load `plotly.js` [from a CDN](https://github.com/plotly/plotly.js?tab=readme-ov-file#load-via-script-tag), use the `PlotlyViaCDNModule` and set on the `version` argument the plotly.js's version you want to use and, optionally, you can also set on the `bundleName` argument the plotly.js's build you want to use:
+
+```typescript
+import { NgModule } from '@angular/core';
+import { CommonModule } from '@angular/common';
+
+import { PlotlyViaCDNModule } from 'angular-plotly.js';
+
+
+@NgModule({
+    imports: [
+        CommonModule,
+        PlotlyViaCDNModule.forRoot({
+            version: '1.55.2' // can be `latest` or any version number (i.e.: '1.40.0')
+            bundleName: 'basic' // optional: can be null (for full) or 'basic', 'cartesian', 'geo', 'gl3d', 'gl2d', 'mapbox' or 'finance'
+        }),
+    ],
+    ...
+})
+export class AppModule { }
+```
+
+By default, plotly's CDN is used to fetch the requested bundle.js. However, you can either choose `plotly`, `cloudflare` or `custom`.
+
+```typescript
+...
+
+// For cloudflare
+PlotlyViaCDNModule.forRoot({
+    version: '1.55.2',
+    cdnProvider: 'cloudflare', // cloudflare doesn't support `latest`. It is mandatory to supply version.
+    bundleName: 'basic' // optional: can be null (for full) or 'basic', 'cartesian', 'geo', 'gl3d', 'gl2d', 'mapbox' or 'finance'
+});
+
+
+// For custom CDN URL
+PlotlyViaCDNModule.loadViaCDN('custom', ); 
+PlotlyViaCDNModule.forRoot({
+    cdnProvider: 'custom', // cloudflare doesn't support `latest`. It is mandatory to supply version.
+    customUrl: 'https://custom.cdn/url' // can be used directly for any self hosted plotly bundle
+});
+
+...
+```
+
+### Plotly Via Window Module
+
+`plotly.js` can be added as a [global script on angular.json](https://github.com/angular/angular-cli/wiki/stories-global-scripts#global-scripts) to avoid it being bundled into the final project's code. To make this happen, you must first add `plotly.js` path into `angular.json` file as shown below:
+
+```javascript
+// angular.json
+{
+    ...
+    "projects": {
+        "project-name": { // This is your project's name
+            ...
+            "architect": {
+                "build": {
+                    ...
+                    "options": {
+                        "scripts": [
+                            "node_modules/plotly.js-dist-min/plotly.min.js" // add this
+                        ]
+                    }
+                }
+            }
+            ...
+        }
+    }
+}
+```
+
+This will include `plotly.js` into the `vendor.js` file generated by angular CLI build process, and `plotly.js` library will be loaded before angular and your project's code. The `window.Plotly` will be available. Thus, you must use `PlotlyViaWindowModule` module to force `angular-plotly.js` to use `window.Plotly` object:
+
+
+```typescript
+import { NgModule } from '@angular/core';
+import { CommonModule } from '@angular/common';
+
+import { PlotlyViaWindowModule } from 'angular-plotly.js';
+
+@NgModule({
+    imports: [CommonModule, PlotlyViaWindowModule],
+    ...
+})
+export class AppModule { }
+```
+
+If you want to use a [different precompiled bundle](https://github.com/plotly/plotly.js/blob/master/dist/README.md#partial-bundles) or if you wish to [assemble you own customized bundle](https://github.com/plotly/plotly.js#modules), you can use `PlotlyViaWindowModule` to force the use of `window.Plotly` object as shown above.
+
+
+
 ## Development
 
 To get started:
