✨ add support for polling when watching file changes (#184)

This can help get hot reloading work when running sensei with a VM-backed Docker from a host file system folder. For example, when running sensei with Docker for Windows with the WSL2 back-end from a Windows file system folder (see #117) or when running sensei with Colima from a macOS file system folder (see lima-vm/lima#615). The recommendation still is to work off the VM file system to get native file watching.

README.md

@@ -20,19 +20,25 @@ The compiler for our training material. Sensei is a replacement for
       --workdir /$(basename $(pwd)) \
       --publish ${SENSEI_PORT:-8080}:${SENSEI_PORT:-8080} \
       --env SENSEI_PORT \
+      --env SENSEI_WATCH_POLL \
       --cap-add=SYS_ADMIN \
       zenika/sensei'
     ```
 
 > ⚠ When running sensei inside a Docker container, the `--material` is limited
 > to descendants of the working directory.
 
+> ⚠ If sensei fails to recompile on changes, try setting `SENSEI_WATCH_POLL` to
+> `true`.
+
 > ⚠ To change `SENSEI_PORT` when using this alias, use the following syntax:
 > `export SENSEI_PORT=9000; sensei`. See
 > [here](https://github.com/Zenika/sensei/issues/147#issuecomment-1091188979).
 
 #### Notes on running in Docker for Windows
 
+> ℹ️ The following also applies to Colima on macOS.
+
 When bind-mounting files in Docker for Windows with WSL2,
 the [recommendation](https://docs.docker.com/desktop/windows/wsl/#best-practices)
 is to store files in the Linux filesystem, i.e. inside WSL2.
@@ -42,7 +48,9 @@ to edit files on the Linux filesystem.
 
 Therefore it is recommended to clone the training repository in the Linux filesystem then to run the alias from WSL2.
 
-> ⚠ If you use the Windows filesystem, hot reload when changing training content won't work.
+> ⚠ If you use the Windows filesystem, hot reload when changing training content
+> won't work out-of-the-box, but you can set `SENSEI_WATCH_POLL` to `true` to
+> enable it.
 
 > ⚠ If you use the Windows filesystem and expect to use the alias within Git Bash for Windows, prepend the
 > `--volume` and `--workdir` options with an additional slash

src/build/webpack.config.js

@@ -10,6 +10,12 @@ const { BundleAnalyzerPlugin } = require("webpack-bundle-analyzer");
 const Prism = require("prismjs");
 require("prismjs/components/")();
 
+/**
+ *
+ * @param {*} env
+ * @param {*} argv
+ * @returns {import("webpack").Configuration}
+ */
 module.exports = (env = {}, argv = {}) => {
   assertRequiredOptionsArePresent(env);
 
@@ -157,8 +163,9 @@ module.exports = (env = {}, argv = {}) => {
         analyzerPort: env.bundleAnalyzer?.port,
       }),
     ],
-    devServer: {
-      contentBase: false,
+    watchOptions: {
+      poll: env.watch?.poll,
+      aggregateTimeout: 300,
     },
   };
 };

src/cli/cli.js

@@ -9,6 +9,11 @@ const webpackConfig = require("../build/webpack.config");
 const webpack = require("webpack");
 const yargs = require("yargs/yargs");
 
+/**
+ *
+ * @param {*} args
+ * @param {ReturnType<typeof composeEnv>} env
+ */
 async function cli(args, env) {
   const {
     _: [command],
@@ -20,10 +25,10 @@ async function cli(args, env) {
     `Processing folder '${options.material}' as '${options.slug}' using slide size ${options.slideWidth}x${options.slideHeight} and language '${options.language}'`
   );
 
-  const { host, port, bundleAnalyzer } = env;
+  const { host, port, bundleAnalyzer, watch } = env;
   switch (command) {
     case "serve":
-      await serve({ ...options, bundleAnalyzer }, { host, port });
+      await serve({ ...options, bundleAnalyzer, watch }, { host, port });
       break;
     case "build":
       await build({ ...options, bundleAnalyzer });
@@ -190,6 +195,7 @@ function composeEnv() {
     SENSEI_BUNDLE_ANALYZER_MODE,
     SENSEI_BUNDLE_ANALYZER_HOST,
     SENSEI_BUNDLE_ANALYZER_PORT,
+    SENSEI_WATCH_POLL,
   } = process.env;
   const bundleAnalyzerExplicitlyEnabled =
     SENSEI_BUNDLE_ANALYZER_ENABLED === "true";
@@ -210,6 +216,7 @@ function composeEnv() {
       host: SENSEI_BUNDLE_ANALYZER_HOST,
       port: SENSEI_BUNDLE_ANALYZER_PORT,
     },
+    watch: { poll: SENSEI_WATCH_POLL === "true" },
   };
 }