diff --git a/demo/start.js b/demo/start.js
index 9240c3c0..b523b761 100644
--- a/demo/start.js
+++ b/demo/start.js
@@ -11,7 +11,16 @@ const startServer = require('./server.js');
 
 startServer();
 
-// Build/watch client source
+/**
+ * This webpack config builds and watches the demo project. It works by taking the output from tsc
+ * (via `yarn watch`) which is put into `out/` and then webpacks it into `demo/dist/`. The aliases
+ * are used fix up the absolute paths output by tsc (because of `baseUrl` and `paths` in
+ * `tsconfig.json`.
+ *
+ * For production builds see `webpack.config.js` in the root directory. If that is built the demo
+ * can use that by switching out which `Terminal` is imported in `client.ts`, this is useful for
+ * validating that the packaged version works correctly.
+ */
 const clientConfig = {
   entry: path.resolve(__dirname, 'client.ts'),
   devtool: 'inline-source-map',
diff --git a/webpack.config.js b/webpack.config.js
index 185ba317..d62cba20 100644
--- a/webpack.config.js
+++ b/webpack.config.js
@@ -5,6 +5,12 @@
 
 const path = require('path');
 
+/**
+ * This webpack config does a production build for xterm.js. It works by taking the output from tsc
+ * (via `yarn watch` or `yarn prebuild`) which are put into `out/` and webpacks them into a
+ * production mode umd library module in `lib/`. The aliases are used fix up the absolute paths
+ * output by tsc (because of `baseUrl` and `paths` in `tsconfig.json`.
+ */
 module.exports = {
   entry: './out/public/Terminal.js',
   resolve: {
@@ -12,7 +18,8 @@ module.exports = {
     extensions: [ '.js' ],
     alias: {
       common: path.resolve('./out/common'),
-      core: path.resolve('./out/core')
+      core: path.resolve('./out/core'),
+      ui: path.resolve('./out/ui')
     }
   },
   output: {