Mop up some issues with bundling system #1027 (#1028)

* Expose some dependencies in node_modules via gh-pages

* Use the .nojekyll trick

* Fix some documentation inaccuracies

.github/workflows/publish-extension.yaml

@@ -90,6 +90,8 @@ jobs:
           git config user.email "<>"
           # Delete gitignore entry for the dist folder
           sed -i "/^\/dist\/$/d" .gitignore
+          # Apply the patch to gitignore to allow some dependencies to be included
+          git apply ./scripts/gitignore.patch
           if [ ! -z "$(git status --porcelain)" ]; then
             git add .
             git commit -m "Set GitHub Pages release version"

CONTRIBUTING.md

@@ -27,14 +27,16 @@ do a one-time setup before you start coding, like this:
   and for Windows [here](https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows);
 * Create a personal fork  of Kiwix JS and clone it locally (for more details, see [Kiwix guidelines](https://github.com/kiwix/overview/blob/main/CONTRIBUTING.md));
 * In a Terminal (Bash, PowerShell) run `npm install` in the project's root directory to install development and bundling dependencies;
-* Test the development server by running `npm run serve`. This will open the (unbundled) source code in your browser. **While viewing this, we strongly recommend
+* Test the development server by running `npm run serve`. This will open the (unbundled) source code in your browser. **While viewing this, we strongly recommend**
-  that you go to configuration and turn on the option to Bypass AppCache under "Expert Settings", as this will ensure you are always looking at the latest version
+  **that you go to configuration and turn on the option to Bypass AppCache under "Expert Settings", as this will ensure you are always looking at the latest version**
-  (otherwise the app caches its own code, and you won't see your changes easily)**. You can exit this server by typing `q` in the Terminal that launched it;
+  (otherwise the app caches its own code, and you won't see your changes easily). You can exit this server by typing `q` in the Terminal that launched it;
 * Test that bundling works by running `npm run preview`. This should build the app and launch a preview of the production code in a server. Again, we strongly recommend,
-  while here, that you turn on the Bypass AppCache option. To exit this server, press `Ctrl-C` in the Terminal that launched it.
+  while here, that you **turn on the Bypass AppCache option**. To exit this server, press `Ctrl-C` in the Terminal that launched it;
+* You can build the bundled version without previewing it with `npm run build`. It will be built to the `/dist` directory.
 
-You can use any Integrated Development Environment (IDE) that you wish. If you don't have a preference, we can recommend [Visual Studio Code](https://code.visualstudio.com/).
+You can use any Integrated Development Environment (IDE) that you wish. If you don't have a preference, we can recommend
-If using this, also install the [ESLint plugin](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) within VS Code.
+[Visual Studio Code](https://code.visualstudio.com/). If using this, also install the
+[ESLint plugin](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) within VS Code.
 
 ## Contributing guidelines
 

README.md

@@ -82,8 +82,11 @@ would suggest that you upgrade to a browser that supports Service Workers (Chrom
 These platforms/browsers are deprecated. We still partially test against them, and we'll try to keep compatibility as long as it's not too complicated:
 
 - Firefox OS >=1.2 (needs to be installed manually on the device with WebIDE)
-- Microsoft Edge Legacy >=15 (needs to run a local copy of the source code)
+- Microsoft Edge Legacy >=15 (needs to run a bundled version of the source code)
-- Microsoft Internet Explorer 11 (needs to run a local copy of the source code)
+- Microsoft Internet Explorer 11 (needs to run a bundled version of the source code)
+
+You can build a bundled version by running `npm install` and `npm run build` in the root directory of this repo. Alternatively, a bundled version is served
+as a web app for testing from https://kiwix.github.io/kiwix-js/dist/ (also available on the `gh-pages` branch of this repo, under `/dist`). 
 
 ### Installing unsigned extensions in Chromium
 
@@ -135,7 +138,9 @@ The browser extensions are distributed through the stores of each vendor (see li
 
 Some nightly builds are generated, and should only be used for testing purpose: https://download.kiwix.org/nightly/.
 
-There is a test implementation of the latest code at https://kiwix.github.io/kiwix-js/, but this is used for development, and may be buggy, experimental or unstable.
+There is a test implementation of the latest code at https://kiwix.github.io/kiwix-js/ (unbundled: needs a modern browser that suppors native ES6 modules), and a bundled version for any
+HTML5 browser (>=IE11) at https://kiwix.github.io/kiwix-js/dist/, but these implementations are used for development, and may be buggy, experimental or unstable. A stable PWA version for
+use in the browser extensions is available from https://browser-extension.kiwix.org/current/.
 
 ## Previous versions
 

scripts/gitignore.patch

@@ -0,0 +1,42 @@
+# DEV: This patch file is used in the publish-extension.yaml workflow to allow some dependenicies in node_modules to be committed to the repo
+# in the gh-pages branch. This is needed because the gh-pages branch is used to publish an implementation of the app. You may need to maintain
+# this list if more dependencies are added to the extension via npm.
+ .gitignore | 24 +++++++++++++++++++++++-
+ 1 file changed, 23 insertions(+), 1 deletion(-)
+
+diff --git a/.gitignore b/.gitignore
+index 69d180f..45218ed 100644
+--- a/.gitignore
++++ b/.gitignore
+@@ -43,7 +43,29 @@ build/config/buildinfo.properties
+ 
+ www-built
+ www-ghdeploy
+-/node_modules/
++/node_modules/*
++!/node_modules/@fortawesome
++/node_modules/@fortawesome/*
++!/node_modules/@fortawesome/fontawesome-free
++/node_modules/@fortawesome/fontawesome-free/*
++!/node_modules/@fortawesome/fontawesome-free/js
++/node_modules/@fortawesome/fontawesome-free/js/*
++!/node_modules/@fortawesome/fontawesome-free/js/all.js
++!/node_modules/bootstrap
++/node_modules/bootstrap/*
++!/node_modules/bootstrap/dist
++/node_modules/bootstrap/dist/*
++!/node_modules/bootstrap/dist/css
++/node_modules/bootstrap/dist/css/*
++!/node_modules/bootstrap/dist/css/bootstrap.min.*
++!/node_modules/bootstrap/dist/js
++/node_modules/bootstrap/dist/js/*
++!/node_modules/bootstrap/dist/js/bootstrap.bundle.min.*
++!/node_modules/jquery
++/node_modules/jquery/*
++!/node_modules/jquery/dist
++/node_modules/jquery/dist/*
++!/node_modules/jquery/dist/jquery.slim.min.*
+ /tmp/
+ /scripts/kiwix-*.pem
+ /scripts/set_secret_environment_variables.sh
+