Principle:Promptfoo Promptfoo Dynamic Module Loading
| Knowledge Sources | |
|---|---|
| Domains | Module_System, Runtime |
| Last Updated | 2026-02-14 07:45 GMT |
Overview
Principle governing the dynamic loading of user-provided JavaScript/TypeScript modules and language-specific wrapper scripts across ESM and CJS environments.
Description
Dynamic Module Loading defines how promptfoo imports user-provided code (custom providers, assertion functions, transforms) at runtime. The principle addresses the challenge of loading arbitrary modules in a codebase that must work in both ESM development (tsx), bundled ESM production, and bundled CJS library modes. It handles path resolution, import() vs require() selection, caching of loaded modules, and location of language wrapper scripts (Python, Ruby, Go).
Usage
Apply this principle when adding new extension points that load user code, or when modifying how wrapper scripts are located.
Theoretical Basis
The module loading system implements a Universal Module Loader pattern that normalizes the differences between ESM and CJS:
- Path resolution handles both absolute paths and file:// URLs
- Environment detection uses compile-time BUILD_FORMAT constants to select the appropriate loading strategy
- Wrapper script location uses a deterministic path calculation from the current module's directory, with caching for performance