Bundle npm dependencies using esbuild (#1574)

Author: cyrus-

.gitattributes

@@ -11,6 +11,7 @@ src/haz3lweb/exercises/**/*.ml linguist-generated
 
 hazel.opam linguist-generated
 hazel.opam.locked linguist-generated
+package-lock.json linguist-generated
 
 *.md linguist-documentation
 docs/** linguist-documentation

.github/workflows/deploy_branches.yml

@@ -16,6 +16,13 @@ jobs:
           path: source
       - name: Add the name of the current branch to the environment as BRANCH_NAME
         uses: nelonoel/[email protected]
+      - name: Install node/npm
+        uses: actions/setup-node@v4
+        with:
+          node-version: 'latest'
+      - name: Install NPM dependencies
+        run: npm install
+        working-directory: ./source
       - name: Set-up OCaml
         uses: ocaml/setup-ocaml@v3
         with:

.gitignore

@@ -59,3 +59,4 @@ hazel.opam.locked.old
 
 # Code coverage
 _coverage/
+node_modules/** 

Makefile

@@ -9,6 +9,7 @@ all: dev
 deps:
 	opam update
 	opam install ./hazel.opam.locked --deps-only --with-test --with-doc
+	npm install
 
 change-deps:
 	opam update

README.md

@@ -17,7 +17,7 @@ can also be accessed at:
 
 ### Short version
 
-If you already have `ocaml` version 5.2.0 and at least version 2.0 of `opam`
+If you already have `ocaml` version 5.2.0, at least version 2.0 of `opam`, and `npm`
 installed, you can build Hazel by running the following commands.
 
 - `git clone [email protected]:hazelgrove/hazel.git`

docs/Change-JS-Dependencies.md

@@ -0,0 +1,45 @@
+# Adding JavaScript Dependencies
+
+Follow these steps to add and manage JavaScript dependencies in the project:
+
+## 1. Add Dependencies to `package.json`
+- Open the `package.json` file in the project root.
+- Add the required dependencies under the `"dependencies"` section.  
+    Example:
+    ```json
+    "dependencies": {
+        "example-library": "^1.0.0"
+    }
+    ```
+
+## 2. Update the Lock File
+- Run the following command to install the new dependencies and update the `package-lock.json` file:
+    ```bash
+    make deps
+    ```
+    **Note:** This command runs `npm install` under the hood. It installs the dependencies listed in the `package.json` file and updates the `package-lock.json` file to reflect the exact versions of the installed packages. This ensures consistent dependency resolution across environments.
+
+## 3. Reference Dependencies in JavaScript Files
+- Make sure the desired dependency is referenced by `src/haz3lweb/www/prebundle.js`
+    Example:
+    ```javascript
+    import exampleLibrary from 'example-library';
+
+    exampleLibrary.doSomething();
+    ```
+- If you add a new toplevel js file (outside of prebundle.js) you need to ensure it is bundled and included
+    - Ensure the `dune` build step is configured to use `esbuild` for bundling the JavaScript files.
+        - This is the current step in `src/haz3lweb/dune`
+            ```dune
+            (rule
+                (targets bundled.js)
+                (action
+                (run
+                %{project_root}/node_modules/esbuild/bin/esbuild
+                prebundle.js
+                --bundle
+                --outfile=bundled.js)))
+            ```
+        - We need the bundled js for every loaded js file we depend on
+            - This means that dependencies should be added to already bundled files or a new bundle needs to be added. 
+    - The dependencies will be bundled automatically during the build process.