From d26705809d7cfcfd6de6250026e552db8d4822a8 Mon Sep 17 00:00:00 2001
From: Andrei Rusu <andrei.rusu@beatfactor.net>
Date: Fri, 28 Jan 2022 12:27:05 +0100
Subject: [PATCH] added plugin api page

---
 guide/configuration/settings.md          |  6 +--
 guide/extending-nightwatch/plugin-api.md | 68 ++++++++++++++----------
 2 files changed, 44 insertions(+), 30 deletions(-)

diff --git a/guide/configuration/settings.md b/guide/configuration/settings.md
index 8e7a1215..f568b8af 100644
--- a/guide/configuration/settings.md
+++ b/guide/configuration/settings.md
@@ -73,13 +73,13 @@ Below are the default settings that will be passed to the Nightwatch instance du
    </tr>
 
     <tr>
-     <td>`backwards_compatibility_mode`<br><span class="optional">since v1.2.2</span></td>
+     <td>`backwards_compatibility_mode`<br><span class="optional">since v2.0</span></td>
      <td>boolean</td>
      <td>false</td>
      <td>In Nightwatch v1.x, when used with `await` operator, API commands will return the full result object as `{value: `<VALUE>`}` whereas in v2, the value is return directly. If using a callback, the behaviour remains unchanged.</td>
    </tr>
     <tr>
-     <td>`disable_global_apis`<br><span class="optional">since v1.2.2</span></td>
+     <td>`disable_global_apis`<br><span class="optional">since v2.0</span></td>
      <td>boolean</td>
      <td>false</td>
      <td>Disable the global apis like `"browser"`, `"element()"`, `"expect()"`; this might be needed if using Nightwatch with third-party libraries.</td>
@@ -117,7 +117,7 @@ The below settings are used to control the way the built-in CLI test runner work
    </tr>
 
   <tr>
-     <td>`enable_fail_fast`<br><span class="optional">since v1.2.2</span></td>
+     <td>`enable_fail_fast`<br><span class="optional">since v2.0</span></td>
      <td>boolean</td>
      <td>false</td>
      <td>Enable aborting the test run execution when the first test failure occurs; the remaining test suites will be skipped.</td>
diff --git a/guide/extending-nightwatch/plugin-api.md b/guide/extending-nightwatch/plugin-api.md
index f9a28107..915bb96f 100644
--- a/guide/extending-nightwatch/plugin-api.md
+++ b/guide/extending-nightwatch/plugin-api.md
@@ -1,36 +1,50 @@
-## Plugin API (alpha)
+## Plugin API (beta)
 Nightwatch `v2.0` also introduces a new interface for defining plugins and extending the base functionality of Nightwatch with your own custom commands and assertions. 
 
-Plugins are essentially wrappers over custom commands and assertions. Plugins are installed in your `node_modules` folder.
+Plugins are essentially wrappers over custom commands and assertions. Plugins are installed in your `node_modules` folder. The plugin API is still in beta at the moment. 
 
-#### Authoring a New Nightwatch Plugin
+#### Authoring a Nightwatch plugin
+If you're new to publishing NPM packages, read the [Creating and publishing unscoped public packages](https://docs.npmjs.com/creating-and-publishing-unscoped-public-packages) guide first.
 
-#### Using The `--reporter` command-line argument
-Define your reporter in a separate file, using the below interface, and then specify the path to the file using the `--reporter` cli argument.
+A Nightwatch plugin needs to be installed from NPM in the same project where Nightwatch is used (or as a global NPM package).
 
-##### Interface:
-<div class="sample-test">
-<pre><code class="language-javascript">
-module.exports = {
-  write : function(results, options, done) {
-    done();
-  }
-};</code></pre>
-</div>
+##### Folder structure:
+The folder structure is very simple and looks like this:
 
-#### The `reporter` method in your external globals
+<pre>
+nightwatch/
+  ├── custom-commands/
+  |   ├── my_new_custom_command.js
+  |   └── my_other_custom_command.js
+  ├── custom-assertions/
+  |   ├── my_new_custom_assertions.js
+  |   └── my_other_custom_command.js
+  ├── index.js
+  ├── LICENSE.md
+  ├── package.json
+  └── README.md
+</pre>
 
-Add your reporter in the external globals file. Read more about [external globals](/guide/using-nightwatch/external-globals.html).
+The Nightwatch runner will pick up the custom commands and assertions automatically if the plugin is defined with the above structure.
 
-See the provided [globalsModule.js](https://github.com/nightwatchjs/nightwatch/blob/main/examples/globalsModule.js) for an example.
+#### Installing a new plugin
+Once the plugin will is available in NPM (or another package repository), you can simply install it in your project folder and then update the Nightwatch config file by adding it to the `plugins` Array.
 
-#### Example:
-<div class="sample-test">
-<pre><code class="language-javascript">
-module.exports = {
-  reporter : function(results, done) {
-    console.log(results);
-    done();
-  }
-};</code></pre>
-</div>
+First, install the plugin from NPM:
+
+<div class="sample-test"><pre data-language="bash"><code class="language-bash">npm i my-new-plugin --save-dev</code></pre></div>
+
+Then update your `nightwatch.conf.js` (or `nightwatch.json`) and add it to the `plugins` list:
+
+<div class="sample-test"><pre data-language="javascript"><code class="language-javascript">{
+  src_folders: [...],
+    
+  plugins: ['my-new-plugin']
+  
+  // other nightwatch config options
+
+}
+</code></pre></div>
+
+#### Example
+See our new `Vite` plugin [vite-plugin-nightwatch](https://github.com/nightwatchjs/vite-plugin-nightwatch) for an example.