refactor(site): webpack configuration (#870)

greyscaled · web-flow · commit 473aa6bd3ae3 · 2022-04-04T18:28:37.000-04:00
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)
diff --git a/site/webpack.common.ts b/site/webpack.common.ts
@@ -3,31 +3,72 @@
  * 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
-  // the bundle script, which might have special naming.
-  new HtmlWebpackPlugin({
-    template: path.join(templatePath, "index.html"),
-    publicPath: "/",
-  }),
-]
+/**
+ * dashboardHTMLPluginConfig is the HtmlWebpackPlugin configuration for the
+ * dashboard chunk.
+ */
+const dashboardHTMLPluginConfig = new HtmlWebpackPlugin({
+  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 -
-  // a bundle that is shared across all of the UI. However, we may need to eventually split
-  // like in v1, where there is a separate entry piont for dashboard & terminal.
-  entry: path.join(__dirname, "src/Main.tsx"),
+  // entry defines each "page" or "chunk". In v1, we have two "pages":
+  // dashboard and terminal. This is desired because the terminal has the xterm
+  // vendor, and it is undesireable to load all of xterm on a dashboard
+  // page load.
+  //
+  // The object key determines the chunk 'name'. This can be used in `output`
+  // to create a final bundle name.
+  //
+  // REMARK: We may need to further vendorize the pieces shared by the chunks
+  //         such as React, ReactDOM. This is not yet _optimized_, but having
+  //         them split means less initial load on dashboard page load.
+  entry: dashboardEntrypoint,
+
+  // output defines the name and location of the final bundle
+  output: {
+    // The chunk name along with a hash of its content will be used for the
+    // generated bundle name.
+    //
+    // REMARK: It's important to use [contenthash] here to invalidate caches.
+    filename: "bundle.[contenthash].js",
+    path: path.resolve(__dirname, "out"),
+  },
 
   // 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: [
@@ -38,28 +79,29 @@ export const commonWebpackConfig: Configuration = {
             },
           },
         ],
-        exclude: [/node_modules/],
+        exclude: /node_modules/,
+      },
+
+      // 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: {
-    // Let webpack know to consider ts/tsx files for bundling
+    // 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"],
   },
 
-  // output defines the name and location of the final bundle
-  output: {
-    // The chunk name along with a hash of its content will be used for the
-    // generated bundle name.
-    //
-    // REMARK: It's important to use [contenthash] here to invalidate caches.
-    filename: "bundle.[contenthash].js",
-    path: path.resolve(__dirname, "out"),
-  },
-
-  plugins: plugins,
-
-  target: "web",
+  // plugins customize the build process
+  plugins: [environmentPlugin, dashboardHTMLPluginConfig],
 }
