From 1aeb87fc321e02075c494205e2009d23283728ec Mon Sep 17 00:00:00 2001
From: Nate Fischer <ntfschr@google.com>
Date: Sun, 12 Oct 2025 00:06:42 -0700
Subject: [PATCH] docs: instructions for plugins

I realized that shelljs plugins actually are working correctly with the
latest shx release, however it's somewhat tricky to set this up
properly. I've documented the steps in a new markdown page.

Fixes #239
---
 PLUGINS.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md  |  6 ++++++
 2 files changed, 57 insertions(+)
 create mode 100644 PLUGINS.md

diff --git a/PLUGINS.md b/PLUGINS.md
new file mode 100644
index 0000000..0c93338
--- /dev/null
+++ b/PLUGINS.md
@@ -0,0 +1,51 @@
+# Plugin support
+
+Did you know that `shx` can also take advantage of all the great
+[ShellJS plugins](https://www.npmjs.com/search?q=keyword%3Ashelljs%2Cplugin)?
+Here's how to get started using plugins with your project:
+
+## Using plugins from inside package.json scripts
+
+```shell
+$ npm install --save-dev shx
+$ npm install --save-dev shelljs-plugin-sleep
+```
+
+Define a file named `.shxrc.json` to tell `shx` which plugins to load:
+
+```json
+{
+  "plugins": [
+    "shelljs-plugin-sleep"
+  ]
+}
+```
+
+Define a script in package.json which invokes the desired `shx` plugin as a
+command:
+
+```json5
+{
+  // Your other package.json stuff goes here...
+  "scripts": {
+    "my-cool-script": "echo 'sleep for 3 seconds' && shx sleep 3"
+  }
+  // ...
+}
+```
+
+And now you can run your package.json script:
+
+```shell
+$ npm run my-cool-script
+```
+
+**Important:** make sure you execute this via the `npm run` script, do not try
+to call `shx` directly from your terminal. If you call `shx` directly in the
+terminal, then `shx` won't be able to import the plugins from your local
+`node_modules/` directory. Calling this via `npm run` script fixes the problem
+because `npm` automatically adds `node_modules/` to the import path.
+
+**Note:** `shx` will only load plugins if a `.shxrc.json` file is present in the
+working directory, so it's recommended to add this JSON file to the top level of
+your project, right next to your project's package.json file.
diff --git a/README.md b/README.md
index f9a6c6a..e6ccf3e 100644
--- a/README.md
+++ b/README.md
@@ -153,6 +153,12 @@ supported options:
 | N/A | N/A | `shx --help` | Show help text. |
 | N/A | N/A | `shx --version` | Print the shx version. |
 
+### Plugin support
+
+Did you know that `shx` can also take advantage of all the great
+[ShellJS plugins](https://www.npmjs.com/search?q=keyword%3Ashelljs%2Cplugin)?
+See [PLUGINS.md](./PLUGINS.md) for instructions.
+
 ## Team
 
 | [![Nate Fischer](https://avatars.githubusercontent.com/u/5801521?s=130)](https://github.com/nfischer) | [![Ari Porad](https://avatars1.githubusercontent.com/u/1817508?v=3&s=130)](http://github.com/ariporad) | [![Levi Thomason](https://avatars1.githubusercontent.com/u/5067638?v=3&s=130)](https://github.com/levithomason) |