Improve docs

README.md

@@ -27,7 +27,7 @@ Zen will autonomously protect your Node.js applications against:
 - 🛡️ [Server-side request forgery (SSRF)](./docs/ssrf.md)
 - 🛡️ [Attack wave detection](https://help.aikido.dev/zen-firewall/zen-features/attack-wave-protection)
 - 🛡️ JS injection
-- 🛡 [IDOR attacks](./docs/idor-protection.md)
+- 🛡️ [IDOR attacks](./docs/idor-protection.md) (opt-in, see setup guide)
 
 Zen operates autonomously on the same server as your Node.js app to:
 
@@ -145,7 +145,17 @@ For framework- and provider- specific instructions, check out our docs:
 - [Google Cloud Functions](docs/cloud-functions.md)
 - [Google Cloud Pub/Sub](docs/pubsub.md)
 
-For ESM applications, see [docs/esm.md](docs/esm.md).
+> [!NOTE]
+> Many TypeScript projects use `import` syntax but still compile to CommonJS — in that case, the setup in the framework docs above works as-is. If your app runs as **native ESM** at runtime (e.g. `"type": "module"` in package.json), see [ESM setup](docs/esm.md) for additional steps.
+
+## Guides
+
+- [Troubleshooting](docs/troubleshooting.md) — common issues and how to debug Zen
+- [ESM support](docs/esm.md) — setup for native ECMAScript module apps
+- [Bundlers](docs/bundler.md) — using Zen with esbuild and other bundlers
+- [Proxy / IP headers](docs/proxy.md) — configure client IP detection behind load balancers
+- [Set the current user](docs/user.md) — identify users for rate limiting, blocking, and attack reports
+- [IDOR protection](docs/idor-protection.md) — prevent data leaks in multi-tenant apps
 
 ## Reporting to your Aikido Security dashboard
 

docs/cloud-functions.md

@@ -12,14 +12,17 @@ functions.http("handler", async (req, res) => {
 });
 ```
 
-or ESM import style:
+or using `import` syntax:
 
 ```js
 import "@aikidosec/firewall/cloud-function";
 
 // ...
 ```
 
+> [!NOTE]
+> Many TypeScript projects use `import` syntax but still compile to CommonJS — in that case, the setup above works as-is. If your app runs as **native ESM** at runtime (e.g. `"type": "module"` in package.json), see [ESM setup](./esm.md) for additional steps.
+
 If you're using the `exports.handler` style, you'll need to wrap your handler manually.
 
 At the very beginning of the file that contains your handler, add the following line:
@@ -35,7 +38,7 @@ exports.handler = protect(async (event, context) => {
 });
 ```
 
-or ESM import style:
+or using `import` syntax:
 
 ```js
 import protect from "@aikidosec/firewall/cloud-function";

docs/express.md

@@ -12,14 +12,17 @@ const app = express();
 // ...
 ```
 
-or ESM import style:
+or using `import` syntax:
 
 ```js
 import "@aikidosec/firewall";
 
 // ...
 ```
 
+> [!NOTE]
+> Many TypeScript projects use `import` syntax but still compile to CommonJS — in that case, the setup above works as-is. If your app runs as **native ESM** at runtime (e.g. `"type": "module"` in package.json), see [ESM setup](./esm.md) for additional steps.
+
 ## Blocking mode
 
 By default, the firewall will run in non-blocking mode. When it detects an attack, the attack will be reported to Aikido if the environment variable `AIKIDO_TOKEN` is set and continue executing the call.

docs/fastify.md

@@ -12,14 +12,17 @@ const fastify = Fastify();
 // ...
 ```
 
-or ESM import style:
+or using `import` syntax:
 
 ```js
 import "@aikidosec/firewall";
 
 // ...
 ```
 
+> [!NOTE]
+> Many TypeScript projects use `import` syntax but still compile to CommonJS — in that case, the setup above works as-is. If your app runs as **native ESM** at runtime (e.g. `"type": "module"` in package.json), see [ESM setup](./esm.md) for additional steps.
+
 ## Blocking mode
 
 By default, the firewall will run in non-blocking mode. When it detects an attack, the attack will be reported to Aikido if the environment variable `AIKIDO_TOKEN` is set and continue executing the call.

docs/hapi.md

@@ -15,14 +15,17 @@ const server = Hapi.server({
 // ...
 ```
 
-or ESM import style:
+or using `import` syntax:
 
 ```js
 import "@aikidosec/firewall";
 
 // ...
 ```
 
+> [!NOTE]
+> Many TypeScript projects use `import` syntax but still compile to CommonJS — in that case, the setup above works as-is. If your app runs as **native ESM** at runtime (e.g. `"type": "module"` in package.json), see [ESM setup](./esm.md) for additional steps.
+
 ## Blocking mode
 
 By default, the firewall will run in non-blocking mode. When it detects an attack, the attack will be reported to Aikido if the environment variable `AIKIDO_TOKEN` is set and continue executing the call.

docs/hono.md

@@ -14,14 +14,17 @@ const app = Hono();
 // ...
 ```
 
-or ESM import style:
+or using `import` syntax:
 
 ```js
 import "@aikidosec/firewall";
 
 // ...
 ```
 
+> [!NOTE]
+> Many TypeScript projects use `import` syntax but still compile to CommonJS — in that case, the setup above works as-is. If your app runs as **native ESM** at runtime (e.g. `"type": "module"` in package.json), see [ESM setup](./esm.md) for additional steps.
+
 ## Blocking mode
 
 By default, the firewall will run in non-blocking mode. When it detects an attack, the attack will be reported to Aikido if the environment variable `AIKIDO_TOKEN` is set and continue executing the call.

docs/koa.md

@@ -14,14 +14,17 @@ app.use(...);
 // ...
 ```
 
-or ESM import style:
+or using `import` syntax:
 
 ```js
 import "@aikidosec/firewall";
 
 // ...
 ```
 
+> [!NOTE]
+> Many TypeScript projects use `import` syntax but still compile to CommonJS — in that case, the setup above works as-is. If your app runs as **native ESM** at runtime (e.g. `"type": "module"` in package.json), see [ESM setup](./esm.md) for additional steps.
+
 Zen also supports `@koa/router` or `koa-router`.
 
 ## Blocking mode

docs/lambda.md

@@ -13,14 +13,17 @@ exports.handler = protect(async (event, context) => {
 });
 ```
 
-or ESM import style:
+or using `import` syntax:
 
 ```js
 import protect from "@aikidosec/firewall/lambda";
 
 // ...
 ```
 
+> [!NOTE]
+> Many TypeScript projects use `import` syntax but still compile to CommonJS — in that case, the setup above works as-is. If your app runs as **native ESM** at runtime (e.g. `"type": "module"` in package.json), see [ESM setup](./esm.md) for additional steps.
+
 Right now, we support the following triggers:
 
 - Gateway API
@@ -52,7 +55,7 @@ exports.handler = protect(
 ```
 <!-- prettier-ignore-end -->
 
-or ESM import style:
+or using `import` syntax:
 
 <!-- prettier-ignore-start -->
 ```js

docs/nestjs.md

@@ -10,6 +10,9 @@ import "@aikidosec/firewall"; // <-- Include this before any other code or impor
 // ...
 ```
 
+> [!NOTE]
+> Many TypeScript projects use `import` syntax but still compile to CommonJS — in that case, the setup above works as-is. If your app runs as **native ESM** at runtime (e.g. `"type": "module"` in package.json), see [ESM setup](./esm.md) for additional steps.
+
 ## Blocking mode
 
 By default, the firewall will run in non-blocking mode. When it detects an attack, the attack will be reported to Aikido if the environment variable `AIKIDO_TOKEN` is set and continue executing the call.

docs/pubsub.md

@@ -19,14 +19,17 @@ subscription.on("message", (message) => {
 // ...
 ```
 
-or ESM import style:
+or using `import` syntax:
 
 ```js
 import "@aikidosec/firewall";
 
 // ...
 ```
 
+> [!NOTE]
+> Many TypeScript projects use `import` syntax but still compile to CommonJS — in that case, the setup above works as-is. If your app runs as **native ESM** at runtime (e.g. `"type": "module"` in package.json), see [ESM setup](./esm.md) for additional steps.
+
 That's it! Your app is now protected by Aikido guard.
 
 If you want to see a full example, check our [Pub/Sub sample app](../sample-apps/pubsub-mongodb).

docs/restify.md

@@ -15,14 +15,17 @@ const server = restify.createServer({
 // ...
 ```
 
-or ESM import style:
+or using `import` syntax:
 
 ```js
 import "@aikidosec/firewall";
 
 // ...
 ```
 
+> [!NOTE]
+> Many TypeScript projects use `import` syntax but still compile to CommonJS — in that case, the setup above works as-is. If your app runs as **native ESM** at runtime (e.g. `"type": "module"` in package.json), see [ESM setup](./esm.md) for additional steps.
+
 ## Blocking mode
 
 By default, the firewall will run in non-blocking mode. When it detects an attack, the attack will be reported to Aikido if the environment variable `AIKIDO_TOKEN` is set and continue executing the call.

docs/troubleshooting.md

@@ -37,7 +37,7 @@ In addition the output contains the name and version of each supported and instr
 
 ## Bundlers & ECMAScript modules (ESM)
 
-If you are using a bundler like esbuild or a framework that uses bundling please ensure to follow the steps described in the [bundler](./bundler.md) docs. Applications using ESM at runtime are not supported yet. TypeScript code is often translated to CommonJS.
+If you are using a bundler like esbuild or a framework that uses bundling please ensure to follow the steps described in the [bundler](./bundler.md) docs. If your application uses native ESM at runtime, see [ESM setup](./esm.md). Note that many TypeScript projects use `import` syntax but still compile to CommonJS — in that case no extra steps are needed.
 
 ## Disable code generation hook