From 99aa1bd7692fdd0b600f9c467d2a73465f5b7fd8 Mon Sep 17 00:00:00 2001
From: Toby Zerner <toby.zerner@gmail.com>
Date: Sat, 24 Feb 2018 16:29:19 +1030
Subject: [PATCH] Add documentation

---
 js-packages/webpack-config/LICENSE   | 22 ++++++++++++++++++++++
 js-packages/webpack-config/README.md | 14 ++++++++++++++
 js-packages/webpack-config/index.js  | 26 ++++++++++++++++----------
 3 files changed, 52 insertions(+), 10 deletions(-)
 create mode 100755 js-packages/webpack-config/LICENSE
 create mode 100755 js-packages/webpack-config/README.md

diff --git a/js-packages/webpack-config/LICENSE b/js-packages/webpack-config/LICENSE
new file mode 100755
index 000000000..b03069095
--- /dev/null
+++ b/js-packages/webpack-config/LICENSE
@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Toby Zerner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
diff --git a/js-packages/webpack-config/README.md b/js-packages/webpack-config/README.md
new file mode 100755
index 000000000..5736da8a0
--- /dev/null
+++ b/js-packages/webpack-config/README.md
@@ -0,0 +1,14 @@
+**Webpack config for Flarum JavaScript compilation.**
+
+This package generates a [Webpack](https://webpack.js.org) config object that will compile JavaScript for use in Flarum. Example usage:
+
+```js
+// webpack.config.js
+var config = require('flarum-webpack-config');
+
+module.exports = config(options);
+```
+
+## Options
+
+* `compatPrefix` Old-style module prefix (eg. `flarum/sticky`) to alias. Setting this will also enable importing old-style core modules (eg. `import foo from 'flarum/foo'`).
diff --git a/js-packages/webpack-config/index.js b/js-packages/webpack-config/index.js
index f9c8427a5..b9a811747 100644
--- a/js-packages/webpack-config/index.js
+++ b/js-packages/webpack-config/index.js
@@ -21,25 +21,31 @@ module.exports = function(options = {}) {
           }
         }
       ]
+    },
+
+    // For backwards compatibility, search for non-relative-path modules
+    // in the `src` and `lib` directories. Also make sure the root node_modules
+    // directory is searched, otherwise importing a module from a file
+    // inside `lib` won't work.
+    resolve: {
+      modules: [
+        path.resolve(process.cwd(), 'src'),
+        path.resolve(process.cwd(), '../lib'),
+        path.resolve(process.cwd(), 'node_modules'),
+        'node_modules'
+      ]
     }
   };
 
-  if (options.compat) {
-    config.resolve = config.resolve || {};
-    config.resolve.modules = [
-      path.resolve(process.cwd(), 'src'),
-      path.resolve(process.cwd(), '../lib'),
-      path.resolve(process.cwd(), 'node_modules'),
-      'node_modules'
-    ];
-  }
-
   if (options.compatPrefix) {
+    // Strip the old-style module prefix from non-relative-path imports by
+    // aliasing it to nothing.
     config.resolve = config.resolve || {};
     config.resolve.alias = {
       [options.compatPrefix]: '.'
     };
 
+    // Support importing old-style core modules.
     config.externals = [
       function(context, request, callback) {
         let matches;