diff --git a/BUILDING.md b/BUILDING.md
new file mode 100644
index 00000000000..639809c394a
--- /dev/null
+++ b/BUILDING.md
@@ -0,0 +1,78 @@
+# Building plotly.js
+
+## Webpack
+
+For plotly.js to build with Webpack you will need to install [ify-loader@v1.1.0+](https://github.com/hughsk/ify-loader) and add it to your `webpack.config.json`. This adds Browserify transform compatibility to Webpack which is necessary for some plotly.js dependencies.
+
+A repo that demonstrates how to build plotly.js with Webpack can be found [here](https://github.com/plotly/plotly-webpack). In short add `ify-loader` to the `module` section in your `webpack.config.js`:
+
+```js
+...
+    module: {
+        rules: [
+            {
+                test: /\.js$/,
+                loader: 'ify-loader'
+            }
+        ]
+    },
+...
+```
+
+## Browserify
+
+Given source file:
+
+```js
+// file: index.js
+
+var Plotly = require('plotly.js');
+
+// ....
+```
+
+then simply run,
+
+
+```
+browserify index.js > bundle.js
+```
+
+to trim meta information (and thus save a few bytes), run:
+
+
+```
+browserify -t path/to/plotly.js/tasks/util/compress_attributes.js index.js > bundle.js
+```
+
+## Angular CLI
+
+Currently Angular CLI uses Webpack under the hood to bundle and build your Angular application.
+Sadly it doesn't allow you to override its Webpack config in order to add the plugin mentioned in the [Webpack](#webpack) section.
+Without this plugin your build will fail when it tries to build glslify for WebGL plots.
+
+Currently 2 solutions exists to circumvent this issue:
+
+1) If you need to use WebGL plots, you can create a Webpack config from your Angular CLI project with [ng eject](https://github.com/angular/angular-cli/wiki/eject). This will allow you to follow the instructions regarding Webpack.
+2) If you don't need to use WebGL plots, you can make a custom build containing only the required modules for your plots. The clean way to do it with Angular CLI is not the method described in the [Modules](https://github.com/plotly/plotly.js/blob/master/README.md#modules) section of the README but the following:
+
+```typescript
+// in the Component you want to create a graph
+import * as Plotly from 'plotly.js';
+```
+
+```json
+// in src/tsconfig.app.json
+// List here the modules you want to import
+// this example is for scatter plots
+{
+    "compilerOptions": {
+        "paths": {
+            "plotly.js": [
+                "../node_modules/plotly.js/lib/core.js",
+                "../node_modules/plotly.js/lib/scatter.js"
+            ]
+        }
+    }
+}
+```
diff --git a/README.md b/README.md
index 05cf93f1aa9..f1b1e83fe03 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,7 @@ and more.
 
 * [Quick start options](#quick-start-options)
 * [Modules](#modules)
+* [Building plotly.js](#building-plotlyjs)
 * [Bugs and feature requests](#bugs-and-feature-requests)
 * [Documentation](#documentation)
 * [Contributing](#contributing)
@@ -103,24 +104,9 @@ Important: the plotly.js code base contains some non-ascii characters. Therefore
 <script src="my-plotly-bundle.js" charset="utf-8"></script>
 ```
 
+## Building plotly.js
 
-#### Building plotly.js with Webpack
-
-For plotly.js to build with Webpack you will need to install [ify-loader@v1.1.0+](https://github.com/hughsk/ify-loader) and add it to your `webpack.config.json`. This adds Browserify transform compatibility to Webpack which is necessary for some plotly.js dependencies.
-
-A repo that demonstrates how to build plotly.js with Webpack can be found [here](https://github.com/rreusser/plotly-webpack). In short add `ify-loader` to the `module` section in your `webpack.config.js`:
-```js
-...
-    module: {
-        rules: [
-            {
-                test: /\.js$/,
-                loader: 'ify-loader'
-            }
-        ]
-    },
-...
-```
+Building instructions using `webpack`, `browserify` and other build frameworks are in [`BUILDING.md`](https://github.com/plotly/plotly.js/blob/master/BUILDING.md)
 
 ## Bugs and feature requests
 
diff --git a/tasks/test_syntax.js b/tasks/test_syntax.js
index 31c2d55b34b..3163322aafb 100644
--- a/tasks/test_syntax.js
+++ b/tasks/test_syntax.js
@@ -205,6 +205,7 @@ function assertFileNames() {
                 base === 'CONTRIBUTING.md' ||
                 base === 'CHANGELOG.md' ||
                 base === 'SECURITY.md' ||
+                base === 'BUILDING.md' ||
                 file.indexOf('mathjax') !== -1
             ) return;