Better document the webpack files to match the work Grey is doing in v1

bryphe-coder · bryphe-coder · commit 7b5e982a0d7d · 2022-03-09T18:27:11.000Z
diff --git a/site/webpack.common.ts b/site/webpack.common.ts
@@ -0,0 +1,57 @@
+/**
+ * @fileoverview This file contains a set of webpack configurations that should
+ * be shared between development and production.
+ */
+
+
+import * as path from "path"
+import { Configuration } from "webpack"
+import HtmlWebpackPlugin from "html-webpack-plugin"
+
+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({
+    title: "Custom template",
+    template: path.join(templatePath, "index.html"),
+    inject: "body",
+  })
+]
+
+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, "Main.tsx"),
+
+  // modules specify how different modules are loaded
+  // See: https://webpack.js.org/concepts/modules/
+  module: {
+    rules: [
+      {
+        test: /\.tsx?$/,
+        use: ["ts-loader"],
+        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: {
+    // 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"),
+  },
+  target: "web",
+}
diff --git a/site/webpack.dev.ts b/site/webpack.dev.ts
@@ -1,17 +1,39 @@
 import ReactRefreshWebpackPlugin from "@pmmmwh/react-refresh-webpack-plugin"
-import HtmlWebpackPlugin from "html-webpack-plugin"
-import * as webpack from "webpack"
+import { Configuration } from "webpack"
 import "webpack-dev-server"
 
-import productionConfig from "./webpack.prod"
+import { commonWebpackConfig } from "./webpack.common"
 
-const config: webpack.Configuration = {
-  ...productionConfig,
+const commonPlugins = commonWebpackConfig.plugins || []
+
+const config: Configuration = {
+  ...commonWebpackConfig,
+
+  // devtool controls how source maps are generated. In development, we want
+  // more details (less optimized) for more readability and an easier time
+  // debugging
+  devtool: "eval-source-map",
+
+  // devServer is the configuration for webpack-dev-server.
+  //
+  // REMARK: needs webpack-dev-server import at top of file for typings
   devServer: {
     allowedHosts: "all",
+
+    // client configures options that are observed in the browser/web-client.
     client: {
+      // automatically sets the browser console to verbose when using HMR
+      logging: "verbose",
+
+      // errors will display as a full-screen overlay
       overlay: true,
-      progress: false,
+
+      // build % progress will display in the browser
+      progress: true,
+
+      // webpack-dev-server uses a webSocket to communicate with the browser
+      // for HMR. By setting this to auto://0.0.0.0/ws, we allow the browser
+      // to set the protocal, hostname and port automatically for us.
       webSocketURL: "auto://0.0.0.0:0/ws",
     },
     devMiddleware: {
@@ -20,22 +42,25 @@ const config: webpack.Configuration = {
     headers: {
       "Access-Control-Allow-Origin": "*",
     },
+
+    // historyApiFallback is required when using history (react-router) for
+    // properly serving index.html on 404s.
     historyApiFallback: true,
     hot: true,
     proxy: {
       "/api": "http://localhost:3000",
     },
     static: ["./static"],
   },
+
+  // Development mode - see:
+  // https://webpack.js.org/configuration/mode/#mode-development
   mode: "development",
   plugins: [
-    new HtmlWebpackPlugin({
-      title: "Custom template",
-      // Load a custom template (lodash by default)
-      template: "html_templates/index.html",
-      inject: "body",
-      hash: true,
-    }),
+    ...commonPlugins,
+
+    // The ReactRefreshWebpackPlugin enables hot-module reloading:
+    // https://github.com/pmmmwh/react-refresh-webpack-plugin
     new ReactRefreshWebpackPlugin({
       overlay: true,
     }),
diff --git a/site/webpack.prod.ts b/site/webpack.prod.ts
@@ -1,40 +1,31 @@
-import * as path from "path"
 import CopyWebpackPlugin from "copy-webpack-plugin"
-import HtmlWebpackPlugin from "html-webpack-plugin"
-import * as webpack from "webpack"
-import "webpack-dev-server"
+import { Configuration } from "webpack"
+import { commonWebpackConfig } from "./webpack.common"
 
-const config: webpack.Configuration = {
-  entry: "./Main.tsx",
+const commonPlugins = commonWebpackConfig.plugins || []
+
+export const config: Configuration = {
+  ...commonWebpackConfig,
   mode: "production",
-  module: {
-    rules: [
-      {
-        test: /\.tsx?$/,
-        use: ["ts-loader"],
-        exclude: [/node_modules/],
-      },
-    ],
+
+  // Don't produce sourcemaps in production, to minmize bundle size
+  devtool: false,
+
+  output: {
+    ...commonWebpackConfig.output,
+
+    // regenerate the entire out/ directory when producing production builds
+    clean: true,
   },
+
   plugins: [
+    ...commonPlugins,
+    // For production builds, we also need to copy all the static
+    // files to the 'out' folder.
     new CopyWebpackPlugin({
       patterns: [{ from: "static", to: "." }],
-    }),
-    new HtmlWebpackPlugin({
-      title: "Custom template",
-      // Load a custom template (lodash by default)
-      template: "html_templates/index.html",
-      inject: "body",
-    }),
-  ],
-  resolve: {
-    extensions: [".tsx", ".ts", ".js"],
-  },
-  output: {
-    filename: "bundle.[contenthash].js",
-    path: path.resolve(__dirname, "out"),
-  },
-  target: "web",
+    })
+  ]
 }
 
 export default config
