docs(storefront): strf-10179 Add environment and debugging setup steps (

#1007)

CONTRIBUTING.md

@@ -11,7 +11,7 @@ They should be gradually refactored with time.
 By contributing to Stencil CLI, you agree that your contributions will be licensed as listed under the
 [README.md](https://github.com/bigcommerce/stencil-cli/blob/master/README.md).
 
-#### Table of Contents
+## Table of Contents
 
 [Stencil Documentation](https://stencil.bigcommerce.com/docs)
 
@@ -21,6 +21,17 @@ By contributing to Stencil CLI, you agree that your contributions will be licens
 -   [Pull Requests](#pull-requests)
 -   [Release stencil-cli](#release-stencil-cli)
 
+[Set up the development environment](#set-up-the-development-environment)
+
+-   [Using a bash/zsh function](#using-a-bashzsh-function)
+-   [Without using a bash/zsh function](#without-using-a-bashzsh-function)
+
+[Debugging locally](#debugging-locally)
+
+-   [Creating a function/alias for debugging](#creating-a-functionalias-for-debugging)
+-   [Using the Chrome NodeJS Debugger](#using-the-chrome-nodejs-debugger)
+-   [Using the VSCode Debugger](#using-the-vscode-debugger)
+
 [Styleguides](#styleguides)
 
 -   [Git Commit Messages](#git-commit-messages)
@@ -72,7 +83,117 @@ Additionally:
 -   Mark private class fields and methods with an underscore (e.g. user.\_password) and @private JSDoc tag
     and avoid using them in other entities (while our current Node version doesn't support native private fields).
 
-### Project best practices
+## Set up the development environment
+
+The easiest method to develop on your local `stencil-cli` fork is to create a function in your `.zshrc` or `.bash_profile`. This will allow you to run your local fork of stencil-cli against a theme without needing to use `npm link` or executing the stencil-cli scripts in the `bin` directory by their absolute path. This is not required, but can make things much easier.
+
+### Using a bash/zsh function
+
+1.  Create your own fork of the `bigcommerce/stencil-cli` GitHub repository
+2.  In your terminal, browse to your chosen directory and `git clone` your stencil-cli fork. Keep this directory in mind.
+3.  Depending on the type of terminal you're using, run the following command:
+    -   **zsh**: `open ~/.zshrc`
+    -   **bash**: `open ~/.bash_profile`
+4.  This will open the file in a text editor. _At the very bottom_ of the file, add the following code: \
+    (**NOTE:** you must replace the `/path/to/` with the appropriate target directory to your stencil-cli `/bin` folder.)
+
+    ```
+    # function for local stencil-cli fork development (stencilDev)
+    function stencilDev() {
+        node $HOME/path/to/stencil-cli/bin/stencil.js $@
+    }
+    ```
+
+5.  Save the file, close it, and restart your terminal.
+
+Now, you will be able to use `stencilDev` as a command to run your local version of stencil-cli from any theme directory.
+
+**Example:**
+
+```
+cd path/to/cornerstone
+
+stencilDev start
+```
+
+### Without using a bash/zsh function
+
+If you do not follow the steps above, you can run your local version of stencil-cli directly by running the `stencil.js` file from node.
+
+**Example:**
+
+```
+cd path/to/cornerstone
+
+node /path/to/stencil-cli/bin/stencil.js start
+```
+
+## Debugging locally
+
+Using the Node debugger is a crucial part of local development and can give you a better idea of how requests are routed through stencil-cli, which code gets executed, and where things might be going wrong.
+
+In order for debugging to be a possibility, you will need to add the `--inspect` flag when launching the `bin/stencil.js` file. Again, we can make things a bit easier with a bash/zsh function.
+
+### Creating a function/alias for debugging
+
+1. Repeat steps 1-3 from the [Using a bash/zsh function](#using-a-bashzsh-function) section.
+2. At the bottom of your terminal environment file (`.zshrc` / `.bash_profile`), add the following code:
+    ```
+    # stencil debug function
+    function stencilDevDebug() {
+        node --inspect $HOME/path/to/stencil-cli/bin/stencil.js $@
+    }
+    ```
+3. Save, exit, and restart your terminal
+
+This will create a new function for you to use when you want to debug your local fork of stencil-cli.
+
+**Example:**
+
+```
+cd path/to/cornerstone
+
+stencilDevDebug start
+```
+
+### Using the Chrome NodeJS Debugger
+
+To use the Chrome Debugger, you should have already executed `stencilDevDebug start` in a theme directory of your choice. This will have started the stencil-cli process with the node inspector attached.
+
+1. Open `localhost:3000` in your Google Chrome browser
+2. Right click, and click on **Inspect** to open the Chrome devtools window
+3. In the DevTools panel at the top left, click on the NodeJS icon (green cube). This will open the Chrome NodeJS Debugger
+4. In the NodeJS Devtools window, you can then use the **Sources** tab to set breakpoints in your code.
+
+### Using the VSCode Debugger
+
+1. Create a `.vscode` directory in your `stencil-cli` folder
+2. Create a new `launch.json` file in the `.vscode` directory, and paste the following code:
+    ```
+    {
+        "version": "0.2.0",
+        "configurations": [
+            {
+            "name": "Attach to Stencil Process ID",
+            "processId": "${command:PickProcess}",
+            "request": "attach",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "type": "node"
+            }
+        ]
+    }
+    ```
+3. Save the file
+4. Run `stencilDevDebug start` in the theme directory of your choice
+5. In VSCode, open the **Run and Debug** panel
+6. In the dropdown, select the `Attach to Stencil Process ID` debug launcher and click the green arrow to start debugging
+7. A dropdown for the process ID will now display at the top of VSCode, select the Node Process that is attached to the debugging port (typically port 9230)
+
+VSCode will now appropriately detect your stencil-cli breakpoints when browsing your store locally.
+
+## Project best practices
 
 **CLI commands:**