feat: support npm workspaces for local development

Decouple clean from build in the Makefile so that watch mode can
rebuild without wiping dist/.  Add nodemon.json and watch:build,
watch:docs, watch:pack scripts to standardize file watching.

Part of #184

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: arbrandes

Makefile

@@ -13,7 +13,7 @@ cat_docs_command = cat ./docs/_API-header.md ./docs/_API-body.md > ./docs/API.md
 clean:
 	rm -rf dist .tsbuildinfo.*
 
-build: clean
+build:
 	tsc --build ./tsconfig.build.json
 	cp ./shell/app.scss ./dist/shell/app.scss
 

README.md

@@ -78,7 +78,7 @@ This watches for changes in `frontend-base` and rebuilds the packaged tarball on
 ```sh
 nvm use
 npm ci
-npm run pack:watch
+npm run watch:pack
 ```
 
 #### In the consuming application

docs/decisions/0010-typescript-compilation-and-local-dev-workflow.rst

@@ -122,7 +122,7 @@ To develop a local dependency (e.g., ``@openedx/frontend-base``) against a
 consuming project:
 
 1. In the dependency: ``npm run pack`` (or use a watcher like ``nodemon`` with
-   ``npm run pack:watch``)
+   ``npm run watch:pack``)
 2. In the consumer: install from the tarball and run the dev server (or use the
    `autoinstall tool`_ from the ``frontend-dev-utils`` package)
 

docs/how_tos/migrate-frontend-app.md

@@ -134,7 +134,7 @@ With the exception of any custom scripts, replace the `scripts` section of your
     "i18n_extract": "openedx formatjs extract",
     "lint": "openedx lint .",
     "lint:fix": "openedx lint --fix .",
-    "prepack": "npm run build",
+    "prepack": "npm run clean && npm run build",
     "snapshot": "openedx test --updateSnapshot",
     "test": "openedx test --coverage --passWithNoTests"
   },
@@ -156,13 +156,15 @@ Also:
 > **Why change `fedx-scripts` to `openedx`?**
 > A few reasons.  One, the Open edX project shouldn't be using the name of an internal community of practice at edX for its frontend tooling.  Two, some dependencies of your MFE invariably still use frontend-build for their own build needs.  This means that they already installed `fedx-scripts` into your `node_modules/.bin` folder.  Only one version can be in there, so we need a new name.  Seemed like a great time for a naming refresh. |
 
-Last but not least, add `clean:` and `build:` targets to your `Makefile`.  The build target compiles TypeScript to JavaScript, uses `tsc-alias` to rewrite `@src` path aliases to relative paths, and copies all SCSS files from `src/` into `dist/` preserving directory structure:
+Last but not least, add `clean:` and `build:` targets to your `Makefile`.  The build target compiles TypeScript to JavaScript, uses `tsc-alias` to rewrite `@src` path aliases to relative paths, and copies all SCSS files from `src/` into `dist/` preserving directory structure.
+
+Note that `build` intentionally does *not* depend on `clean`.  This allows incremental rebuilds during development (especially in workspace mode, where a watcher triggers `build` on every change).  The `prepack` script in `package.json` runs `clean && build` explicitly, so published packages always start fresh.
 
 ```makefile
 clean:
 	rm -rf dist
 
-build: clean
+build:
 	tsc --project tsconfig.build.json
 	tsc-alias -p tsconfig.build.json
 	find src -type f -name '*.scss' -exec sh -c '\
@@ -248,6 +250,7 @@ node_modules
 npm-debug.log
 coverage
 dist/
+packages/
 /*.tgz
 
 ### i18n ###
@@ -952,3 +955,75 @@ Refactor slots
 First, rename `src/plugin-slots`, if it exists, to `src/slots`.  Modify imports and documentation across the codebase accordingly.
 
 Next, the frontend-base equivalent to `<PluginSlot />` is `<Slot />`, and has a different API.   This includes a change in the slot ID, according to the [new slot naming ADR](../decisions/0009-slot-naming-and-lifecycle.rst) in this repository.  Rename them accordingly. You can refer to the `src/shell/dev` in this repository for examples.
+
+
+Set up npm workspaces for local development
+===========================================
+
+Frontend apps support `npm workspaces <https://docs.npmjs.com/cli/using-npm/workspaces>`_ so that developers can work on the app and its dependencies (such as ``frontend-base``) simultaneously, with changes reflected automatically.
+
+Add the workspaces field to package.json
+-----------------------------------------
+
+```diff
++ "workspaces": [
++   "packages/*"
++ ],
+```
+
+This tells npm to look in ``packages/`` for local overrides of published packages.  The ``packages/`` directory is gitignored (see the `.gitignore` step above), since it contains development-only bind-mounted checkouts.
+
+Add a nodemon.json file
+------------------------
+
+Create a ``nodemon.json`` at the repository root.  This configures the ``watch:build`` script to rebuild automatically when source files change:
+
+```json
+{
+  "watch": [
+    "src"
+  ],
+  "ext": "js,jsx,ts,tsx,scss"
+}
+```
+
+Add workspace-aware scripts
+----------------------------
+
+Install ``concurrently`` and ``nodemon`` as dev dependencies:
+
+```sh
+npm install --save-dev concurrently nodemon
+```
+
+Then add the following scripts to ``package.json``:
+
+```json
+"build:packages": "npm run build --workspaces --if-present",
+"dev:packages": "npm run build:packages && concurrently 'npm run watch:build --workspaces --if-present' 'npm run dev'",
+"watch:build": "nodemon --exec 'npm run build'",
+```
+
+- ``watch:build`` uses ``nodemon`` to watch for source changes (as configured in ``nodemon.json``) and re-runs ``npm run build`` on each change.
+- ``build:packages`` runs ``build`` in every workspace package that has the script (i.e., ``frontend-base``), then in the app itself.  This is a one-shot build with no watching.
+- ``dev:packages`` does an initial ``build:packages``, then concurrently watches all workspace packages for changes and starts the dev server.
+
+Using workspaces
+-----------------
+
+To develop against a local ``frontend-base``:
+
+```sh
+mkdir -p packages/frontend-base
+sudo mount --bind /path/to/frontend-base packages/frontend-base
+npm install
+npm run dev:packages
+```
+
+Bind mounts are used instead of symlinks because Node.js resolves symlinks to real paths, which breaks hoisted dependency resolution.  Docker volume mounts work equally well (and are what ``tutor dev`` uses).
+
+When done, unmount with:
+
+```sh
+sudo umount packages/frontend-base
+```

nodemon.json

@@ -0,0 +1,16 @@
+{
+  "watch": [
+    "runtime",
+    "shell",
+    "tools",
+    "index.ts",
+    "types.ts"
+  ],
+  "ext": "ts,tsx,js,jsx,json,scss,css",
+  "ignore": [
+    "node_modules/**",
+    ".git/**",
+    "pack/**"
+  ],
+  "delay": 250
+}

nodemon.pack.json

@@ -25,13 +25,14 @@
     "clean": "make clean",
     "dev": "npm run build && node ./dist/tools/cli/openedx.js dev:shell",
     "docs": "jsdoc -c jsdoc.json",
-    "docs:watch": "nodemon -w runtime -w docs/template -w README.md -e js,jsx,ts,tsx --exec npm run docs",
     "lint": "eslint .; npm run lint:tools; npm --prefix ./test-site run lint",
     "lint:tools": "cd ./tools && eslint . && cd ..",
     "pack": "mkdir -p pack && npm pack --silent --pack-destination pack >/dev/null && mv \"$(ls -t pack/*.tgz | head -n 1)\" pack/openedx-frontend-base.tgz",
-    "pack:watch": "nodemon --config nodemon.pack.json",
     "prepack": "npm run build",
-    "test": "jest"
+    "test": "jest",
+    "watch:build": "nodemon --exec 'npm run build'",
+    "watch:docs": "nodemon --watch docs/template --watch README.md --exec npm run docs",
+    "watch:pack": "nodemon --exec 'npm run pack'"
   },
   "repository": {
     "type": "git",