From 07b10bbc16ab16ba73f3990f3b888e98661aabea Mon Sep 17 00:00:00 2001
From: Colin McDonnell <colinmcd94@gmail.com>
Date: Thu, 14 Sep 2023 17:28:03 -0700
Subject: Clean up trustedDependencies guide

---
 docs/guides/install/trusted.md | 27 ++++++++++++++++++++++++---
 1 file changed, 24 insertions(+), 3 deletions(-)

(limited to 'docs/guides/install')

diff --git a/docs/guides/install/trusted.md b/docs/guides/install/trusted.md
index 3dc14aa94..d0d841eea 100644
--- a/docs/guides/install/trusted.md
+++ b/docs/guides/install/trusted.md
@@ -4,10 +4,25 @@ name: Add a trusted dependency
 
 Unlike other npm clients, Bun does not execute arbitrary lifecycle scripts for installed dependencies, such as `postinstall` and `node-gyp` builds. These scripts represent a potential security risk, as they can execute arbitrary code on your machine.
 
+{% callout %}
+Soon, Bun will include a built-in allow-list that automatically allows lifecycle scripts to be run by popular packages that are known to be safe. This is still under development.
+{% /callout %}
+
+---
+
+If you are seeing one of the following errors, you are probably trying to use a package that uses `postinstall` to work properly:
+
+- `error: could not determine executable to run for package`
+- `InvalidExe`
+
 ---
 
 To tell Bun to allow lifecycle scripts for a particular package, add the package to `trustedDependencies` in your package.json.
 
+Note that this only allows lifecycle scripts for the specific package listed in `trustedDependencies`, _not_ the dependencies of that dependency!
+
+<!-- Bun maintains an allow-list of popular packages containing `postinstall` scripts that are known to be safe. To run lifecycle scripts for packages that aren't on this list, add the package to `trustedDependencies` in your package.json. -->
+
 ```json-diff
   {
     "name": "my-app",
@@ -16,14 +31,20 @@ To tell Bun to allow lifecycle scripts for a particular package, add the package
   }
 ```
 
-<!-- Bun maintains an allow-list of popular packages containing `postinstall` scripts that are known to be safe. To run lifecycle scripts for packages that aren't on this list, add the package to `trustedDependencies` in your package.json. -->
+---
+
+Once this is added, run a fresh install. Bun will re-install your dependencies and properly install
+
+```sh
+$ rm -rf node_modules
+$ rm bun.lockb
+$ bun install
+```
 
 ---
 
 Note that this only allows lifecycle scripts for the specific package listed in `trustedDependencies`, _not_ the dependencies of that dependency!
 
-Soon, Bun will include a built-in allow-list that automatically allows lifecycle scripts to be run by popular packages that are known to be safe. This is still under development.
-
 ---
 
 See [Docs > Package manager > Trusted dependencies](/docs/cli/install#trusted-dependencies) for complete documentation of trusted dependencies.
-- 
cgit v1.2.3