@ha-bits/cortex 1.0.3 → 1.0.4

package/README.md

@@ -39,6 +39,26 @@ npx @ha-bits/cortex server --config ./config.json
 
 The CLI requires a configuration file. See the documentation for configuration options.
 
+## Technical Notes
+
+### Dynamic Module Loading
+
+Cortex uses `createRequire` from Node.js's `module` API instead of the standard `require()` for loading modules at runtime. This is necessary because:
+
+1. **Bundler Compatibility**: When the code is bundled with esbuild/webpack then ncc, the bundler transforms `require()` calls and creates a static context that can't resolve paths determined at runtime.
+
+2. **Dynamic Path Resolution**: Activepieces modules are downloaded to `/tmp/habits-nodes/` or wherever the env points to at runtime and their paths aren't known at build time. Using `createRequire(__filename)` creates a fresh require function that bypasses the bundler's static analysis.
+
+3. **Production Environment**: In production (`/app/dist/pack/index.cjs`), the bundled code would throw "Cannot find module" errors with regular `require()` because webpack's `webpackEmptyContext` can't resolve dynamic paths.
+
+```typescript
+// Instead of: require(dynamicPath)  // ❌ Fails in bundled code
+// We use:
+import { createRequire } from 'module';
+const dynamicRequire = createRequire(__filename);
+const loadedModule = dynamicRequire(dynamicPath);  // ✅ Works in bundled code
+```
+
 ## License
 
 Apache-2.0