MAINT: Use yarn as package manager

.github/dependabot.yml

@@ -3,7 +3,7 @@
 
 version: 2
 updates:
-  - package-ecosystem: "npm"
+  - package-ecosystem: "yarn"
     directory: "/" # Location of package[-lock].json
     schedule:
       interval: "weekly"

.github/workflows/npm-publish.yml

@@ -14,9 +14,9 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v1
         with:
-          node-version: 12
+          node-version: 15
           registry-url: https://registry.npmjs.org/
-      - run: npm ci
-      - run: npm publish
+      - run: yarn install --frozen-lockfile
+      - run: yarn publish
         env:
           NODE_AUTH_TOKEN: ${{secrets.npm_token}}

.github/workflows/test.yml

@@ -31,19 +31,19 @@ jobs:
         uses: actions/cache@v2
         with:
           path: node_modules
-          key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('package-lock.json') }}
           restore-keys: |
-            ${{ runner.os }}-npm-
+            ${{ runner.os }}-yarn-
 
       - name: "Install"
         run: |
-          npm ci
+          yarn install --frozen-lockfile
 
-      - name: "`npm run fmt` and check for changes"
+      - name: "`nary run fmt` and check for changes"
         run: |
-          # If this fails, run `npm run fmt` and push the result
+          # If this fails, run `yarn run fmt` and push the result
           # amend if you feel so inclined.
-          npm run fmt
+          yarn run fmt
           git diff --exit-code
 
   test:
@@ -54,7 +54,7 @@ jobs:
     strategy:
       fail-fast: false # Do not cancel all jobs if one fails
       matrix:
-        node_version: ["10", "12", "14"]
+        node_version: ["12", "14", "15"]
 
     steps:
       - name: "Checkout repo"
@@ -71,18 +71,18 @@ jobs:
         uses: actions/cache@v2
         with:
           path: node_modules
-          key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('yarn-lock.json') }}
           restore-keys: |
-            ${{ runner.os }}-npm-
+            ${{ runner.os }}-yarn-
 
       - name: "Install dependencies"
         run: |
-          npm ci
+          yarn install --frozen-lockfile
 
       - name: "Run tests"
         run: |
-          npm run test
-          npm run test:e2e
+          yarn run test
+          yarn run test:e2e
 
       # Action Repo: https://github.com/codecov/codecov-action
       - name: "Upload coverage to codecov"

.gitignore

@@ -1,6 +1,7 @@
 build
 node_modules
 npm-debug.log
+package-lock.json
 target
 node
 src/_tmp

.npmrc

@@ -0,0 +1,2 @@
+legacy-peer-deps=true
+package-lock=false

docs/Makefile

@@ -17,16 +17,16 @@ help:
 .PHONY: help Makefile
 
 package.json:
-	npm ls
+	yarn ls
 
-package-lock.json: package.json
+yarn-lock.json: package.json
 	# package.json updated, refresh lock with npm install
-	npm install
+	yarn install
 	touch $@
 
-$(JSDOC): package-lock.json
-	# install from package-lock
-	npm ci
+$(JSDOC): yarn-lock.json
+	# install from yarn-lock
+	yarn install --frozen-lockfile
 	# refresh mtime
 	test -f $@ && touch $@
 

docs/contribute.md

@@ -8,7 +8,7 @@ Thanks for your interest in contributing to `thebe`, your contributions are welc
 
 ## Contributing guide
 
-See the [ExecutableBooks developer guidelines](https://executablebooks.org/en/latest/contributing.html) for conventions and practices around developing `thebe`. However, note that some practices, such as creating releases, may be different because `thebe` is primarily an `npm` package rather than a Python package.
+See the [ExecutableBooks developer guidelines](https://executablebooks.org/en/latest/contributing.html) for conventions and practices around developing `thebe`. However, note that some practices, such as creating releases, may be different because `thebe` is primarily an Javascript (`npm`) package rather than a Python package.
 
 ## Repository structure
 
@@ -26,39 +26,63 @@ In order to get Thebe running locally, you'll need to have Node installed on you
 Minimum requirements are:
 
 - nodejs v15.0 or greater
-- npm v7.0 or greater
+- npm v6.0 or greater
+- yarn v1.22 or greater
 
 You can install it in several ways, the most common being:
 
 - Install Node by [following the nodejs instructions](https://nodejs.org/en/download/)
+- Using the [node version manager](https://github.com/nvm-sh/nvm#installing-and-updating)
 - Install Node through `conda`
 
-  ```bash
-  conda install -c conda-forge nodejs
-  ```
+```bash
+conda install -c conda-forge nodejs
+```
 
-Once installed, this also includes `npm` (Node Package Manager) which is what you will run in order to run Thebe locally.
+Once installed, also install `yarn` which is what you will run in order to run Thebe locally.
+
+```bash
+npm install -g yarn
+```
 
-Next, clone the repository and set up your `npm` environment for this repo:
+Next, clone the repository and install the required dependencies:
 
 ```bash
 git clone https://github.com/executablebooks/thebe
 cd thebe
-npm ci
+yarn install
 ```
 
+This will install all dependencies needed to run `thebe` (specified in `package.json`). By default, `yarn install` will also have created a production build in `lib`
+
+If you are using `npm` v7 you may encounter **Peer Dependency Errors** see comments below to resolve these.
+
 ```{note}
-Using `npm ci` rather than `npm install` will ensure that you install the latest tested dependencies, and will not make any unintentional local upgrades.
+Using `yarn install` will ensure that you install the latest tested dependencies, and will not make any unintentional local upgrades. `yarn` uses `npm` under the hood, please do not use `npm install` directly to install dependencies.
+```
+
+#### Peer Dependency Errors
+
+Due to recent changes in `npm` as of v7 peer dependency issues are flagged as critical errors. However, may projects have not yet resolves these issues in their code base, this means that a project's co-dependencies can prevent installation of a package. This is a know issue, to resolve this there are two options:
+
+1. Downgrade `npm` to v6
+
+```bash
+  npm install -g npm@6
 ```
 
-This will install all dependencies needed to run `thebe` (specified in `package.json`).
+2. Set the `legacy-peer-deps` option in your local environment
+
+```bash
+  npm config set legacy-peer-deps true
+```
 
 ## Build and demo `thebe` locally
 
 To use your local copy of `thebe` (e.g., if you make any changes to the `src/` folder), you can run a local build and serve a sample web page. To do so, run:
 
 ```bash
-npm run build:watch
+yarn run build:watch
 ```
 
 This will build `thebe/` locally (including any changes you've made to the source code).
@@ -67,7 +91,7 @@ You can now demo the latest `thebe/` changes by opening the file at `development
 
 The content of `development.html` is a simple HTML page that demonstrates Thebe functionality. You can edit it to test out new features or configurations.
 
-Running the `npm run develop` command will start building the source code with webpack and serve it along with `development.html`.
+Running the `yarn run develop` command will start building the source code with webpack and serve it along with `development.html`.
 As you change the code in `src/`,
 the javascript will automatically be re-built,
 but you'll be required to refresh the page.
@@ -76,28 +100,28 @@ but you'll be required to refresh the page.
 
 Thebe uses code autoformatting so you don't need to worry about style lint,
 so whenever you are ready to commit changes
-run `npm run fmt` to autoformat the javascript.
+run `yarn run fmt` to autoformat the javascript.
 You can put this script in `.git/hooks/pre-commit`:
 
 ```bash
 #!/bin/sh
 if [[ -f package.json ]]; then
-    npm run fmt
+    yarn run fmt
 fi
 ```
 
 to run auto-formatting prior to each commit.
 
 ## Testing Thebe
 
-You can test manually, interactively by running `npm run develop` to open and serve `development.html` with the current build of thebe.
+You can test manually, interactively by running `yarn run develop` to open and serve `development.html` with the current build of thebe.
 
 ### Running automated tests
 
 There are two types of automated test environment in place in thebe both using the Jest testing library. These are:
 
-1.  a standard javascript testing setup for unit / component level testing of the thebe library. These can be run using `npm run test` or `npm run test:watch` and test code is located in the `test` folder.
-2.  e2e style tests using jest + puppeteer that can be run `npm run test:e2e` or `npm run test:e2e:watch` and test code is located in the `e2e` folder.
+1.  a standard javascript testing setup for unit / component level testing of the thebe library. These can be run using `yarn run test` or `yarn run test:watch` and test code is located in the `test` folder.
+2.  e2e style tests using jest + puppeteer that can be run `yarn run test:e2e` or `yarn run test:e2e:watch` and test code is located in the `e2e` folder.
 
 Alternately, you can push your changes to GitHub and let the tests run automatically via GitHub Actions.
 
@@ -125,12 +149,12 @@ Adding new e2e tests involves:
 - load the fixture page at the start of your test
 
 ```javascript
-  beforeAll(async () => {
-   await page.goto(
-     `file:${path.join(__dirname, "/fixtures/HTML/readonly1.html")}`,
-     { waitUntil: ["load", "domcontentloaded", "networkidle0"] }
-   );
- });
+beforeAll(async () => {
+  await page.goto(
+    `file:${path.join(__dirname, "/fixtures/HTML/readonly1.html")}`,
+    { waitUntil: ["load", "domcontentloaded", "networkidle0"] }
+  );
+});
 ```
 
 - Assert on initial page state
@@ -166,8 +190,8 @@ To release thebe, follow the [EBP guidelines](https://executablebooks.org/en/lat
 
 Once prepared, bump the version with:
 
-1. Use npm to update the thebe version in the `package.json` file and to create
-   a git tag for the version using `npm version NEW_VERSION`, e.g. `npm version 0.5.1`
+1. Use yarn to update the thebe version in the `package.json` file and to create
+   a git tag for the version using `yarn version NEW_VERSION`, e.g. `yarn version 0.5.1`
 2. Push the tag to github: `git push --follow-tags`
 3. Create a release for the new tag on github at
    https://github.com/executablebooks/thebe/releases/new; this will trigger a