diff --git a/website/docs/developer-docs/contributing.md b/website/docs/developer-docs/contributing.md
index 1706be12adac..e600077f3bda 100644
--- a/website/docs/developer-docs/contributing.md
+++ b/website/docs/developer-docs/contributing.md
@@ -120,7 +120,7 @@ When you are creating an enhancement suggestion, please fill in [the template](h
 
 authentik can be run locally, although depending on which part you want to work on, different prerequisites are required.
 
-This is documented in the [developer docs](./setup/frontend-dev-environment.md).
+This is documented in the [developer docs](./setup/frontend-dev-environment.mdx).
 
 ### Help with the docs
 
diff --git a/website/docs/developer-docs/setup/_npm-install-scripts-admonition.mdx b/website/docs/developer-docs/setup/_npm-install-scripts-admonition.mdx
new file mode 100644
index 000000000000..23c5d6a2a178
--- /dev/null
+++ b/website/docs/developer-docs/setup/_npm-install-scripts-admonition.mdx
@@ -0,0 +1,11 @@
+:::info NPM install scripts are disabled by default
+The repository's NPM runtime configuration file (`.npmrc`) sets `ignore-scripts=true`. This means that `preinstall`/`install`/`postinstall` lifecycle scripts do not run during `npm ci`. This neutralizes a dominant NPM supply-chain attack pattern at the cost of skipping a few legitimate native-binary unpacks.
+
+If the watch build fails because a package needs its install script (commonly `esbuild`, `chromedriver`, `tree-sitter`, or `tree-sitter-json`), rebuild only that package, for example:
+
+```shell
+npm rebuild --foreground-scripts esbuild chromedriver tree-sitter tree-sitter-json
+```
+
+**Do not** edit `.npmrc` to flip `ignore-scripts` off — that re-introduces the risk repository-wide.
+:::
diff --git a/website/docs/developer-docs/setup/frontend-dev-environment.md b/website/docs/developer-docs/setup/frontend-dev-environment.mdx
similarity index 95%
rename from website/docs/developer-docs/setup/frontend-dev-environment.md
rename to website/docs/developer-docs/setup/frontend-dev-environment.mdx
index 03bcb0256ce1..1f31a59b5b2e 100644
--- a/website/docs/developer-docs/setup/frontend-dev-environment.md
+++ b/website/docs/developer-docs/setup/frontend-dev-environment.mdx
@@ -8,6 +8,8 @@ tags:
     - docker
 ---
 
+import NPMInstallScriptsAdmonition from "./\_npm-install-scripts-admonition.mdx";
+
 If you're focusing solely on frontend development, you can create a minimal development environment using Docker and Node.js. This setup allows you to make and preview changes to the frontend in real-time, without needing to interact with the backend.
 
 ### Prerequisites
@@ -55,6 +57,8 @@ If you're focusing solely on frontend development, you can create a minimal deve
     make web-watch
     ```
 
+    <NPMInstallScriptsAdmonition />
+
 5. In a new terminal, navigate to the cloned repository root and start the backend containers with Docker Compose.
 
     ```shell
diff --git a/website/docs/developer-docs/setup/full-dev-environment.mdx b/website/docs/developer-docs/setup/full-dev-environment.mdx
index ca9d5bb5dff4..88c474641459 100644
--- a/website/docs/developer-docs/setup/full-dev-environment.mdx
+++ b/website/docs/developer-docs/setup/full-dev-environment.mdx
@@ -11,6 +11,7 @@ tags:
 
 import TabItem from "@theme/TabItem";
 import Tabs from "@theme/Tabs";
+import NPMInstallScriptsAdmonition from "./\_npm-install-scripts-admonition.mdx";
 
 ## Prerequisites
 
@@ -126,6 +127,8 @@ Install all required JavaScript and Python dependencies and create an isolated P
 make install
 ```
 
+<NPMInstallScriptsAdmonition />
+
 ### Generate development configuration
 
 Create a local configuration file that uses the local databases for development: