refactor(site): webpack configuration (#870)

This refactor introduces the following changes:

* re-order and re-comment items to match v1
* add EnvironmentPlugin for environment variables
* remove target (unnecessary, we will use browserslist)

site/webpack.common.ts

@@ -3,51 +3,52 @@
  * be shared between development and production.
  */
 
-import * as path from "path"
-import { Configuration } from "webpack"
 import HtmlWebpackPlugin from "html-webpack-plugin"
+import * as path from "path"
+import { Configuration, EnvironmentPlugin } from "webpack"
 
+/**
+ * environmentPlugin sets process.env.* variables so that they're available in
+ * the application.
+ */
+const environmentPlugin = new EnvironmentPlugin({
+  INSPECT_XSTATE: "",
+})
+console.info(`--- Setting INSPECT_XSTATE to '${process.env.INSPECT_XSTATE || ""}'`)
+console.info(`--- Setting NODE_ENV to '${process.env.NODE_ENV || ""}'`)
+
+/**
+ * dashboardEntrypoint is the top-most module in the dashboard chunk.
+ */
+const dashboardEntrypoint = path.join(__dirname, "src/Main.tsx")
+
+/**
+ * templatePath is the path to HTML templates for injecting webpack bundles
+ */
 const templatePath = path.join(__dirname, "html_templates")
 
-const plugins = [
+/**
-  // The HTML webpack plugin tells webpack to use our `index.html` and inject
+ * dashboardHTMLPluginConfig is the HtmlWebpackPlugin configuration for the
-  // the bundle script, which might have special naming.
+ * dashboard chunk.
-  new HtmlWebpackPlugin({
+ */
-    template: path.join(templatePath, "index.html"),
+const dashboardHTMLPluginConfig = new HtmlWebpackPlugin({
-    publicPath: "/",
+  publicPath: "/",
-  }),
+  template: path.join(templatePath, "index.html"),
-]
+})
 
 export const commonWebpackConfig: Configuration = {
-  // entry defines each "page" or "chunk". Currently, for v2, we only have one bundle -
+  // entry defines each "page" or "chunk". In v1, we have two "pages":
-  // a bundle that is shared across all of the UI. However, we may need to eventually split
+  // dashboard and terminal. This is desired because the terminal has the xterm
-  // like in v1, where there is a separate entry piont for dashboard & terminal.
+  // vendor, and it is undesireable to load all of xterm on a dashboard
-  entry: path.join(__dirname, "src/Main.tsx"),
+  // page load.
-
+  //
-  // modules specify how different modules are loaded
+  // The object key determines the chunk 'name'. This can be used in `output`
-  // See: https://webpack.js.org/concepts/modules/
+  // to create a final bundle name.
-  module: {
+  //
-    rules: [
+  // REMARK: We may need to further vendorize the pieces shared by the chunks
-      {
+  //         such as React, ReactDOM. This is not yet _optimized_, but having
-        test: /\.tsx?$/,
+  //         them split means less initial load on dashboard page load.
-        use: [
+  entry: dashboardEntrypoint,
-          {
-            loader: "ts-loader",
-            options: {
-              configFile: "tsconfig.prod.json",
-            },
-          },
-        ],
-        exclude: [/node_modules/],
-      },
-    ],
-  },
-
-  resolve: {
-    // Let webpack know to consider ts/tsx files for bundling
-    // See: https://webpack.js.org/guides/typescript/
-    extensions: [".tsx", ".ts", ".js"],
-  },
 
   // output defines the name and location of the final bundle
   output: {
@@ -59,7 +60,48 @@ export const commonWebpackConfig: Configuration = {
     path: path.resolve(__dirname, "out"),
   },
 
-  plugins: plugins,
+  // modules specify how different modules are loaded
+  // See: https://webpack.js.org/concepts/modules/
+  module: {
+    rules: [
+      // TypeScript (ts, tsx) files use ts-loader for simplicity.
+      //
+      // REMARK: We may want to configure babel-loader later on for further
+      //         optimization (build time, tree-shaking). babel-loader on its
+      //         own does not run type checks.
+      {
+        test: /\.tsx?$/,
+        use: [
+          {
+            loader: "ts-loader",
+            options: {
+              configFile: "tsconfig.prod.json",
+            },
+          },
+        ],
+        exclude: /node_modules/,
+      },
 
-  target: "web",
+      // REMARK: webpack 5 asset modules
+      {
+        test: /\.(png|svg|jpg|jpeg|gif)$/i,
+        type: "asset/resource",
+      },
+    ],
+  },
+
+  // resolve extend/modify how modules are resolved.
+  //
+  // REMARK: Do not add aliases here, unless they cannot be defined in a
+  //         tsconfig file (see TSConfigWebpackPlugin).
+  resolve: {
+    // extensions are attempted in order and enable importing files without
+    // the extensions explicitly stated
+    //
+    // See: https://webpack.js.org/guides/typescript/
+    extensions: [".tsx", ".ts", ".js"],
+  },
+
+  // plugins customize the build process
+  plugins: [environmentPlugin, dashboardHTMLPluginConfig],
 }