diff --git a/docs/esm.md b/docs/esm.md index 3a97a8705..0756d5d03 100644 --- a/docs/esm.md +++ b/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.