[#62] Add the initial version of Brunch & Webpack guides

README.md

@@ -1,7 +1,7 @@
 # Torch
 [![Slackin](https://infiniteredcommunity.herokuapp.com/badge.svg)](https://infiniteredcommunity.herokuapp.com/)
 [![Hex.pm](https://img.shields.io/hexpm/v/torch.svg)](https://hex.pm/packages/torch)
-[![Build Status](https://semaphoreci.com/api/v1/projects/b2c7b27b-ce6c-4b1c-b2a4-df3390f80380/1248783/shields_badge.svg)](https://semaphoreci.com/ir/torch)
+[![Build Status](https://semaphoreci.com/api/v1/projects/b2c7b27b-ce6c-4b1c-b2a4-df3390f80380/1368593/shields_badge.svg)](https://semaphoreci.com/ir/torch)
 [![Deps Status](https://beta.hexfaktor.org/badge/all/github/infinitered/torch.svg)](https://beta.hexfaktor.org/github/infinitered/torch)
 
 Torch is a rapid admin generator for Phoenix apps. It uses generators rather than DSLs to ensure that the code remains maintainable.
@@ -68,47 +68,18 @@ If you want to customize the look and feel of your admin, you should use the SAS
 @import "~torch/assets/css/app";
 ```
 
-Then, update your `brunch-config.js` (or asset manager of choice) SASS settings to make it watch your node_modules directory:
+The `admin_variables` file was generated when you ran `mix torch.install`.
 
-```js
-plugins: {
-  sass: {
-    mode: 'native',
-    includePaths: ['node_modules']
-  }
-}
-```
-
-Then, simply uncomment and customize the variables in `web/static/css/_admin_variables.scss` to change how Torch is styled.
+Then, simply uncomment and customize the variables in `admin_variables.scss` to change how Torch is styled.
 
 ### Using Precompiled CSS
 
-If you're not using SASS, then you will need to configure your asset pipeline to compile the precompiled `torch.css`. Brunch can be configured to do this like so:
-
-1. Add `node_modules` to the watched directories for `stylesheets`.
-
-```js
-stylesheets: {
-  joinTo: {
-    'css/app.css': /^(web|node_modules)/
-  }
-}
-```
-
-2. Add `torch` to the npm configuration:
+If you're not using SASS, then you will need to configure your asset pipeline to compile the precompiled `torch.css`.
 
-```js
-npm: {
-  enabled: true
-  styles: {
-    torch: [
-      'priv/static/torch.css'
-    ]
-  }
-}
-```
+Using Webpack? [Check out the Webpack guide](/docs/guides/webpack.md)
+Using Brunch? [Check out the Brunch guide](/docs/guides/brunch.md)
 
-### Test CSS Instalation
+### Test CSS Installation
 
 To test that you have torch styles and static assets installed and bundled properly, you can add a torch test componet to your markup. In HTML, the test components looks like this:
 

docs/guides/brunch.md

@@ -0,0 +1,41 @@
+## Brunch Configuration for Torch
+
+### Using Sass Variables
+
+Update your `brunch-config.js` SASS settings to make it watch your node_modules directory:
+
+NOTE: We recommend you use yarn for best results rather than npm. NPM >5.0 is currently less stable than yarn.
+
+```js
+plugins: {
+  sass: {
+    mode: 'native',
+    includePaths: ['node_modules']
+  }
+}
+```
+
+### Using Precompiled Assets
+
+1. Add `node_modules` to the watched directories for `stylesheets`.
+
+```js
+stylesheets: {
+  joinTo: {
+    'css/app.css': /^(web|node_modules)/
+  }
+}
+```
+
+2. Add `torch` to the npm configuration:
+
+```js
+npm: {
+  enabled: true
+  styles: {
+    torch: [
+      'priv/static/torch.css'
+    ]
+  }
+}
+```

docs/guides/webpack.md

@@ -0,0 +1,241 @@
+## Webpack Configuration for Torch
+
+Below is an example `webpack.config.js` (version 3.0.0) that imports Torch javascript, css,
+fonts, & images correctly.
+
+NOTE: We recommend you use yarn for best results rather than npm. NPM >5.0 is currently less stable than yarn.
+
+```javascript
+var path = require('path')
+var ExtractTextPlugin = require('extract-text-webpack-plugin')
+var CopyWebpackPlugin = require('copy-webpack-plugin')
+var env = process.env.MIX_ENV || 'dev'
+var isProduction = (env === 'prod')
+
+module.exports = {
+  entry: {
+    'app': ['./js/app.js', './css/app.sass']
+  },
+
+  output: {
+    path: path.resolve(__dirname, '../priv/static/'),
+    filename: 'js/[name].js'
+  },
+
+  devtool: 'source-map',
+
+  module: {
+    rules: [{
+      // SASS Loader
+      test: /\.(sass|scss)$/,
+      include: /css/,
+      use: ExtractTextPlugin.extract({
+        fallback: 'style-loader',
+        use: [
+          {
+            loader: 'css-loader',
+            options: {
+              minimize: isProduction,
+              sourceMap: true
+            }
+          },
+          {
+            loader: 'resolve-url-loader'
+          },
+          {
+            loader: 'sass-loader',
+            options: {
+              sourceComments: !isProduction,
+              sourceMap: true
+            }
+          }
+        ]
+      })
+    }, {
+      // JS Loader
+      test: /\.js?$/,
+      include: /js/,
+      exclude: /node_modules/,
+      use: [{
+        loader: 'babel-loader',
+        query: {
+          presets: ['es2015'],
+          plugins: [],
+          cacheDirectory: true
+        }
+      }]
+    },
+    {
+      // Image Loader
+      test: /\.(png|svg|jpg|gif)$/,
+      exclude: /(fonts|node_modules)/,
+      use: [{
+        loader: 'file-loader',
+        options: {
+          name: '[name].[ext]',
+          outputPath: '../images/'
+        }
+      }]
+    },
+    {
+      // Font Loader
+      test: /\.(woff|woff2|eot|ttf|otf|svg)$/,
+      exclude: /(images|node_modules)/,
+      use: [{
+        loader: 'file-loader',
+        options: {
+          name: '[name].[ext]',
+          outputPath: 'fonts/'
+        }
+      }]
+    },
+    {
+      // Torch Image Loader
+      test: /torch.+images.+\.(png|svg|jpg|gif)$/,
+      use: [{
+        loader: 'file-loader',
+        options: {
+          name: '[name].[ext]',
+          outputPath: 'images/',
+          publicPath: '../'
+        }
+      }]
+    },
+    {
+      // Torch Font Loader
+      test: /torch.+fonts.+\.(woff|woff2|eot|ttf|otf|svg)$/,
+      use: [{
+        loader: 'file-loader',
+        options: {
+          name: '[name].[ext]',
+          outputPath: 'fonts/',
+          publicPath: '../'
+        }
+      }]
+    }]
+  },
+
+  plugins: [
+    new CopyWebpackPlugin([{ from: './static/images', to: 'images' }]),
+    new CopyWebpackPlugin([{ from: './static/robots.txt' }]),
+    new ExtractTextPlugin('css/app.css')
+  ]
+}
+```
+
+### Break Down
+
+#### Sass Loader
+
+This is a pretty standard sass loader including all `.sass` or `.scss` files in the
+`/css/` directory.
+
+```javascript
+{
+  // SASS Loader
+  test: /\.(sass|scss)$/,
+  include: /css/,
+  use: ExtractTextPlugin.extract({
+    fallback: 'style-loader',
+    use: [
+      {
+        loader: 'css-loader',
+        options: {
+          minimize: isProduction,
+          sourceMap: true
+        }
+      },
+      {
+        loader: 'resolve-url-loader'
+      },
+      {
+        loader: 'sass-loader',
+        options: {
+          sourceComments: !isProduction,
+          sourceMap: true
+        }
+      }
+    ]
+  })
+}
+```
+
+#### JS Loader
+
+Also a pretty standard JS loader, including all files with the `.js` extension withing
+the `/js/` folder and excluding `node_modules`.
+
+```javascript
+{
+  // JS Loader
+  test: /\.js?$/,
+  include: /js/,
+  exclude: /node_modules/,
+  use: [{
+    loader: 'babel-loader',
+    query: {
+      presets: ['es2015'],
+      plugins: [],
+      cacheDirectory: true
+    }
+  }]
+}
+```
+
+#### Font & Image Loaders
+
+The first set of font & image loaders load images & fonts within your project, while the
+Torch font & image loaders load fonts and images from torch into the `priv/static` directory.
+
+```javascript
+{
+  // Image Loader
+  test: /\.(png|svg|jpg|gif)$/,
+  exclude: /(fonts|node_modules)/,
+  use: [{
+    loader: 'file-loader',
+    options: {
+      name: '[name].[ext]',
+      outputPath: '../images/'
+    }
+  }]
+},
+{
+  // Font Loader
+  test: /\.(woff|woff2|eot|ttf|otf|svg)$/,
+  exclude: /(images|node_modules)/,
+  use: [{
+    loader: 'file-loader',
+    options: {
+      name: '[name].[ext]',
+      outputPath: 'fonts/'
+    }
+  }]
+},
+{
+  // Torch Image Loader
+  test: /torch.+images.+\.(png|svg|jpg|gif)$/,
+  use: [{
+    loader: 'file-loader',
+    options: {
+      name: '[name].[ext]',
+      outputPath: 'images/',
+      publicPath: '../'
+    }
+  }]
+},
+{
+  // Torch Font Loader
+  test: /torch.+fonts.+\.(woff|woff2|eot|ttf|otf|svg)$/,
+  use: [{
+    loader: 'file-loader',
+    options: {
+      name: '[name].[ext]',
+      outputPath: 'fonts/',
+      publicPath: '../'
+    }
+  }]
+}
+```
+
+

lib/mix/tasks/torch.install.ex

@@ -41,26 +41,19 @@ defmodule Mix.Tasks.Torch.Install do
        update your app.scss file to look like this:
 
         @import "admin_variables";
-        @import "../../../node_modules/torch/web/static/css/torch";
+        @import "~torch/assets/css/app";
 
-       You should also update SASS plugin settings in `brunch-config.js`:
+    2. Configure your asset builder to include node_modules
 
-        plugins: {
-          sass: {
-            mode: 'native',
-            include_paths: ['node_modules']
-          }
-        }
+      Using Brunch? Checkout the Brunch guide: http://github.com/infinitered/torch/docs/guides/brunch.md
+      Using webpack? Checkout the webpack guide: http://github.com/infinitered/torch/docs/guides/webpack.md
 
-       Torch also provides a precompiled CSS file in `priv/static/css/torch.css`
-       if you are not using SASS.
-
-    2. Import the Javascript in your `app.js` file. Requires that your `package.json`
+    3. Import the Javascript in your `app.js` file. Requires that your `package.json`
        has been updated as described in the README.
 
         import 'torch'
 
-    3. Add an admin scope to your router in `router.ex`:
+    4. Add an admin scope to your router in `router.ex`:
 
         scope "/admin", #{Mix.Torch.base}.Admin, as: :admin do
           pipe_through :browser