From d2fa975fe8e8b73a114c0a0a29e6fac33aad1630 Mon Sep 17 00:00:00 2001
From: Jordan Eldredge <jordan@jordaneldredge.com>
Date: Tue, 7 May 2024 17:21:16 -0700
Subject: [PATCH] Document webamp/lazy import

---
 packages/webamp/CHANGELOG.md  |  1 +
 packages/webamp/docs/usage.md | 39 +++++++++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/packages/webamp/CHANGELOG.md b/packages/webamp/CHANGELOG.md
index 39c71311..61183791 100644
--- a/packages/webamp/CHANGELOG.md
+++ b/packages/webamp/CHANGELOG.md
@@ -5,6 +5,7 @@
 - Allow a single mouse drag across the EQ to set all values [#1180](https://github.com/captbaritone/webamp/pull/1180)
 - Configure the initial layout of windows -- size, position, openness, shade mode -- when constructing a Webamp instance.
 - Configure if "double size mode" should be enabled when constructing a Webamp instance.
+- Optically allow users to lazily load heavy dependencies like JSZip and music-metadata-browser with the `webamp/lazy` entry point.
 
 ### Internal Improvements:
 
diff --git a/packages/webamp/docs/usage.md b/packages/webamp/docs/usage.md
index 958a7b41..3fb6397c 100644
--- a/packages/webamp/docs/usage.md
+++ b/packages/webamp/docs/usage.md
@@ -90,6 +90,8 @@ const track = {
     defaultName: 'My Song',
 
     // Optional. Data to be used _instead_ of trying to fetch ID3 tags.
+    // **WARNING** If you omit this data, Webamp will fetch the first
+    // few bytes of this file on load to try to read its id3 tags.
     metaData: {
         artist: 'Jordan Eldredge',
         title: "Jordan's Song"
@@ -97,6 +99,8 @@ const track = {
 
     // Optional. Duration (in seconds) to be used instead of
     // fetching enough of the file to measure its length.
+    // **WARNING** If you omit this property, Webamp will fetch the first
+    // few bytes of this file on load to try to determine its duration.
     duration: 95
 };
 ```
@@ -110,6 +114,8 @@ The `Winamp` class has the following _static_ methods:
 Returns a true if the current browser supports the features that Webamp depends upon. It is recommended to check this before you attempt to instantiate an instance of `Winamp`.
 
 ```JavaScript
+import Webamp from 'webamp';
+
 if(Winamp.browserIsSupported()) {
     new Winamp({/* ... */});
     // ...
@@ -440,6 +446,39 @@ When you are done with a Webamp instance, call this method and Webamp will attem
 webamp.dispose();
 ```
 
+## Optimizing Bundle Size
+
+**Since** UNRELEASED
+
+By default the Webamp import/bundle includes a few heavy dependencies. `JSZip` for extracting user defined skin files and `music-metadata-browser` for reading ID3 tags. If you are using the default skin and supply metadata and duration for all your preloaded tracks, neither of these dependencies are needed for initial load and can instead be lazily loaded only when they are needed. To do this, you can import from `webamp/lazy` instead of `webamp`.
+
+First you'll need to install the dependencies in your project:
+
+```bash
+npm install jszip music-metadata-browser@^0.6.1
+```
+
+The "lazy" version of Webamp will require that you inject functions for lazily importing these dependencies.
+
+```ts
+import Webamp from "webamp/lazy";
+
+const webamp = new Webamp({
+  initialTracks: [
+    {
+      url: "https://example.com/track1.mp3",
+      metaData: {
+        artist: "Jordan Eldredge",
+        title: "Jordan's Song",
+      },
+      duration: 95,
+    },
+  ],
+  requireJSZip: () => import("jszip/dist/jszip"),
+  requireMusicMetadata: () => import("music-metadata-browser/dist/index"),
+});
+```
+
 ## Notes
 
 - Internet Explorer is not supported.