Merge pull request #18 from tapava/develop

docs: added minification warning for remoteDependencies

Author: tapava

README.md

@@ -390,12 +390,32 @@ const kit = new ComputeKit({
   ],
 });
 
+// Declare the global type for TypeScript support
+declare const _: typeof import('lodash');
+
 kit.register('processData', (data: number[]) => {
-  // @ts-ignore - lodash loaded via importScripts
   return _.chunk(data, 3);
 });
 ```
 
+> ⚠️ **Important: Minification Compatibility**
+>
+> When using remote dependencies, use `declare const` instead of `import` to ensure compatibility with production minifiers (Vite, esbuild, etc.).
+>
+> ```typescript
+> // ✅ Correct - works after minification
+> declare const dayjs: typeof import('dayjs');
+> kit.register('format', (d) => dayjs(d).format());
+>
+> // ❌ Incorrect - breaks after minification
+> import dayjs from 'dayjs';
+> kit.register('format', (d) => dayjs(d).format());
+> ```
+>
+> This is because minifiers rename imported variables but preserve free variables declared with `declare const`.
+
+````
+
 #### Methods
 
 | Method                       | Description                   |
@@ -414,7 +434,7 @@ await kit.run('myFunction', data, {
   signal: abortController.signal, // Abort support
   onProgress: (p) => {}, // Progress callback
 });
-```
+````
 
 ---
 

docs/api-reference.md

@@ -44,6 +44,10 @@ new ComputeKit(options?: ComputeKitOptions)
 | `useSharedMemory`    | `boolean`  | `true`                                 | Use SharedArrayBuffer when available  |
 | `remoteDependencies` | `string[]` | `[]`                                   | External scripts to load in workers   |
 
+{: .note }
+
+> When using `remoteDependencies`, use `declare const` instead of `import` for the libraries. See [Using External Libraries]({{ site.baseurl }}/examples#using-external-libraries) for details on minification compatibility.
+
 ---
 
 ## Typed Registry

docs/examples.md

@@ -376,13 +376,15 @@ const kit = new ComputeKit({
   ],
 });
 
+// Declare globals for TypeScript support (and minification compatibility!)
+declare const math: typeof import('mathjs');
+declare const _: typeof import('lodash');
+
 kit.register('advancedMath', (expression: string) => {
-  // @ts-ignore - math.js loaded via importScripts
   return math.evaluate(expression);
 });
 
 kit.register('processData', (data: number[]) => {
-  // @ts-ignore - lodash loaded via importScripts
   return _.chain(data)
     .filter((n) => n > 0)
     .map((n) => n * 2)
@@ -394,6 +396,22 @@ const result = await kit.run('advancedMath', 'sqrt(16) + sin(pi/2)');
 console.log(result); // 5
 ```
 
+{: .warning }
+
+> **Important: Minification Compatibility**
+>
+> Always use `declare const` instead of `import` for libraries loaded via `remoteDependencies`. Minifiers rename imported variables, breaking function serialization in production builds.
+>
+> ```typescript
+> // ✅ Correct - preserved after minification
+> declare const dayjs: typeof import('dayjs');
+> kit.register('format', (d) => dayjs(d).format());
+>
+> // ❌ Incorrect - "dayjs" gets renamed to "a" or similar
+> import dayjs from 'dayjs';
+> kit.register('format', (d) => dayjs(d).format());
+> ```
+
 ---
 
 ## Live Demo

docs/getting-started.md

@@ -154,6 +154,11 @@ const kit = new ComputeKit({
     'https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.21/lodash.min.js',
   ],
 });
+
+// When using remoteDependencies, declare globals instead of importing
+declare const _: typeof import('lodash');
+
+kit.register('chunk', (arr: number[]) => _.chunk(arr, 2));
 ```
 
 ---

docs/react-hooks.md

@@ -52,6 +52,10 @@ function App() {
 | `debug`              | `boolean`  | `false`                         | Enable debug logging         |
 | `remoteDependencies` | `string[]` | `[]`                            | External scripts for workers |
 
+{: .note }
+
+> When using `remoteDependencies`, use `declare const` instead of `import` for external libraries to ensure minification compatibility. See the [Examples page]({{ site.baseurl }}/examples#using-external-libraries) for details.
+
 ---
 
 ## useComputeKit

packages/core/README.md

@@ -58,15 +58,31 @@ const kit = new ComputeKit({
   ],
 });
 
+// Declare the global type for TypeScript support
+declare const _: typeof import('lodash');
+
 // Now you can use lodash inside your compute functions
 kit.register('processData', (data: number[]) => {
-  // @ts-ignore - lodash is loaded via importScripts
   return _.chunk(data, 3);
 });
 ```
 
 **Note:** Remote scripts must be served with proper CORS headers.
 
+> ⚠️ **Minification Warning**
+>
+> Use `declare const` instead of `import` for remote dependencies. Minifiers rename imported variables, which breaks function serialization:
+>
+> ```typescript
+> // ✅ Works after minification
+> declare const dayjs: typeof import('dayjs');
+> kit.register('format', (d) => dayjs(d).format());
+>
+> // ❌ Breaks after minification
+> import dayjs from 'dayjs';
+> kit.register('format', (d) => dayjs(d).format());
+> ```
+
 ### `kit.register(name, fn)`
 
 Register a function to run in workers.