Merge pull request #847 from AikidoSec/dotenv

Add note about loading env variables in ESM mode

Author: hansott

docs/esm.md

@@ -15,9 +15,22 @@ Alternatively, you can set the `NODE_OPTIONS` environment variable to include th
 export NODE_OPTIONS='-r @aikidosec/firewall/instrument'
 ```
 
-> [!IMPORTANT]  
+> [!IMPORTANT]
 > Please also check the documentation on how to integrate Zen with your used web framework.
 
+## Loading environment variables
+
+When using `--require`/`-r` to preload the Zen firewall, the instrumentation hook runs before your application code. This means environment variables loaded by packages like `dotenv` will not be available when Zen starts.
+
+To ensure `AIKIDO_TOKEN` and other environment variables are available during instrumentation, use Node.js's native `--env-file` flag:
+
+```sh
+node --env-file=.env -r @aikidosec/firewall/instrument your-app.js
+```
+
+> [!NOTE]
+> The `--env-file` flag cannot be used in `NODE_OPTIONS`.
+
 ## Known issues
 
 - Zen can not protect ESM sub-dependencies of an ESM package. For example if an ESM package `foo` imports a sub-dependency `bar` that is also an ESM package, Zen will not be able to protect the code in `bar`. This is because the V8 engine does not allow Node.js to observe the evaluation of inner ESM packages (yet). Open issue: [Adding an evaluation hook for v8::Module](https://issues.chromium.org/u/1/issues/384413088). See a full example below.