From 7f1af84e058f79766ca4ca57ed361cde6e75c02a Mon Sep 17 00:00:00 2001
From: Chris Van Emmerik <chris@greenlinkservices.com>
Date: Sun, 19 May 2019 04:06:38 -0600
Subject: [PATCH] Document importable scripts

---
 lang/en/docs/package-json.md | 44 ++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/lang/en/docs/package-json.md b/lang/en/docs/package-json.md
index 0e247a3d2..e6788c57e 100644
--- a/lang/en/docs/package-json.md
+++ b/lang/en/docs/package-json.md
@@ -274,6 +274,50 @@ Certain script names are special. If defined, the `preinstall` script is called
 
 The `start` script value defaults to `node server.js`.
 
+As an alternative, scripts may also be imported from a javascript file.  This allows for customization such as comments, metadata and structuring or grouping scripts.
+
+```json
+{
+  "scripts": "package-scripts.js",  
+}
+```
+
+For defining scripts within the js file, the following structures are supported:
+
+1.  Structure as a standard object hash inside of the scripts object.  This is identical to how scripts are specified in the     packages.json file with the additional ability of comments.    
+
+        module.exports = {
+          scripts: {
+            "build-project": "node build-project.js" // Build project
+          },
+        };
+
+2.  Structure a script as an object with a 'script' key.  This allows for additional metadata to be co-located with an associated script. When a script key is specified within an object, the object's remaining non object values are ignored.  Remaining objects are imported normally.
+
+        module.exports = {
+          scripts: {
+            "test": {
+              script: "node test-project.js",
+              description: "Run tests",                
+            },
+            "build-project": "node build-project.js"
+          },
+        };
+
+3.  Group scripts together using objects with an optional 'default' key.  When scripts are grouped together, the script name or key will be generated from the object hierarchy and the delimiter.  If no delimiter is specified, then '.' will be used by default.  For example, the test.watch script below will be exposed via 'yarn test.watch'.  If a script is specified under an object's 'default' key, it will inherit the parent name.  In the below example, the test.default script will be exposed via 'yarn test'.
+
+        module.exports = {
+          delimiter: '.',
+          scripts: {
+            "test": {
+              default: "cross-env CI=1 react-scripts test --env=jsdom",                
+              watch: "react-scripts test --env=jsdom",
+            },            
+            "build": "rollup -c",
+            "start": "rollup -c -w",            
+          },
+        };
+
 ### `config` <a class="toc" id="toc-config" href="#toc-config"></a>
 
 ```json