webpacker-for-component 1.0.0 → 1.1.0

data/docs/props.md

@@ -0,0 +1,105 @@
+# Props
+
+
+## React
+
+If you need more advanced React-integration, like server rendering, redux, or react-router, see [shakacode/react_on_rails](https://github.com/shakacode/react_on_rails), [react-rails](https://github.com/reactjs/react-rails), and [webpacker-react](https://github.com/renchap/webpacker-react).
+
+If you're not concerned with view helpers to pass props or server rendering, can do it yourself:
+
+```erb
+<%# views/layouts/application.html.erb %>
+
+<%= content_tag :div,
+  id: "hello-react",
+  data: {
+    message: 'Hello!',
+    name: 'David'
+}.to_json do %>
+<% end %>
+```
+
+```js
+// app/javascript/packs/hello_react.js
+
+const Hello = props => (
+  <div className='react-app-wrapper'>
+    <img src={clockIcon} alt="clock" />
+    <h5 className='hello-react'>
+      {props.message} {props.name}!
+    </h5>
+  </div>
+)
+
+// Render component with data
+document.addEventListener('DOMContentLoaded', () => {
+  const node = document.getElementById('hello-react')
+  const data = JSON.parse(node.getAttribute('data'))
+
+  ReactDOM.render(<Hello {...data} />, node)
+})
+```
+
+
+## Vue
+
+Add the data as attributes in the element you are going to use (or any other element for that matter).
+
+```erb
+<%= content_tag :div,
+  id: "hello-vue",
+  data: {
+    message: "Hello!",
+    name: "David"
+  }.to_json do %>
+<% end %>
+```
+
+This should produce the following HTML:
+
+```html
+<div id="hello-vue" data="{&quot;message&quot;:&quot;Hello!&quot;,&quot;name&quot;:&quot;David&quot;}"></div>
+```
+
+Now, modify your Vue app to expect the properties.
+
+```html
+<template>
+  <div id="app">
+    <p>{{test}}{{message}}{{name}}</p>
+  </div>
+</template>
+
+<script>
+  export default {
+    // A child component needs to explicitly declare
+    // the props it expects to receive using the props option
+    // See https://vuejs.org/v2/guide/components.html#Props
+    props: ["message","name"],
+    data: function () {
+      return {
+          test: 'This will display: ',
+      }
+    }
+  }
+</script>
+
+<style>
+</style>
+
+```
+
+```js
+document.addEventListener('DOMContentLoaded', () => {
+  // Get the properties BEFORE the app is instantiated
+  const node = document.getElementById('hello-vue')
+  const props = JSON.parse(node.getAttribute('data'))
+
+  // Render component with props
+  new Vue({
+    render: h => h(App, { props })
+  }).$mount('#hello-vue');
+})
+```
+
+You can follow same steps for Angular too.

data/docs/testing.md

@@ -0,0 +1,45 @@
+# Testing
+
+
+## Lazy compilation
+
+Webpacker lazily compiles assets in test env so you can write your tests without any extra
+setup and everything will just work out of the box.
+
+Here is a sample system test case with hello_react example component:
+
+```js
+// Example react component
+
+import React from 'react'
+import ReactDOM from 'react-dom'
+import PropTypes from 'prop-types'
+
+const Hello = props => (
+  <div>Hello David</div>
+)
+
+document.addEventListener('DOMContentLoaded', () => {
+  ReactDOM.render(
+    <Hello />,
+    document.body.appendChild(document.createElement('div')),
+  )
+})
+```
+
+```erb
+<%# views/pages/home.html.erb %>
+
+<%= javascript_pack_tag "hello_react" %>
+```
+
+```rb
+# Tests example react component
+require "application_system_test_case"
+class HomesTest < ApplicationSystemTestCase
+  test "can see the hello message" do
+    visit root_url
+    assert_selector "h5", text: "Hello! David"
+  end
+end
+```

data/docs/troubleshooting.md

@@ -0,0 +1,65 @@
+# Troubleshooting
+
+
+## ENOENT: no such file or directory - node-sass
+
+*  If you get this error `ENOENT: no such file or directory - node-sass` on Heroku
+or elsewhere during `assets:precompile` or `bundle exec rails webpacker:compile`
+then you would need to rebuild node-sass. It's a bit of a weird error;
+basically, it can't find the `node-sass` binary.
+An easy solution is to create a postinstall hook - `npm rebuild node-sass` in
+`package.json` and that will ensure `node-sass` is rebuilt whenever
+you install any new modules.
+
+
+## Can't find hello_react.js in manifest.json
+
+* If you get this error `Can't find hello_react.js in manifest.json`
+when loading a view in the browser it's because Webpack is still compiling packs.
+Webpacker uses a `manifest.json` file to keep track of packs in all environments,
+however since this file is generated after packs are compiled by webpack. So,
+if you load a view in browser whilst webpack is compiling you will get this error.
+Therefore, make sure webpack
+(i.e `./bin/webpack-dev-server`) is running and has
+completed the compilation successfully before loading a view.
+
+
+## throw er; // Unhandled 'error' event
+
+* If you get this error while trying to use Elm, try rebuilding Elm. You can do
+  so with a postinstall hook in your `package.json`:
+
+```
+"scripts": {
+  "postinstall": "npm rebuild elm"
+}
+```
+
+
+## webpack or webpack-dev-server not found
+
+* This could happen if  `webpacker:install` step is skipped. Please run `bundle exec rails webpacker:install` to fix the issue.
+
+* If you encounter the above error on heroku after upgrading from Rails 4.x to 5.1.x, then the problem might be related to missing `yarn` binstub. Please run following commands to update/add binstubs:
+
+```bash
+bundle config --delete bin
+./bin/rails app:update:bin # or rails app:update:bin
+```
+
+
+## Running Webpack on Windows
+
+If you are running Webpack on Windows, your command shell may not be able to interpret the preferred interpreter
+for the scripts generated in `bin/webpack` and `bin/webpack-dev-server`. Instead you'll want to run the scripts
+manually with Ruby:
+
+```
+C:\path>ruby bin\webpack
+C:\path>ruby bin\webpack-dev-server
+```
+
+
+## Invalid configuration object. Webpack has been initialised using a configuration object that does not match the API schema.
+
+If you receive this error when running `$ ./bin/webpack-dev-server` ensure your configuration is correct; most likely the path to your "packs" folder is incorrect if you modified from the original "source_path" defined in `config/webpacker.yml`.

data/docs/typescript.md

@@ -0,0 +1,116 @@
+# Typescript
+
+
+## Typescript with React
+
+1. Setup react using webpacker [react installer](#react). Then add required depedencies
+for using typescript with React:
+
+```bash
+yarn add ts-loader typescript @types/react @types/react-dom
+```
+
+2. Add a `tsconfig.json` to project root:
+
+``` json
+{
+  "compilerOptions": {
+    "declaration": false,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "lib": ["es6", "dom"],
+    "module": "es6",
+    "moduleResolution": "node",
+    "sourceMap": true,
+    "jsx": "react",
+    "target": "es5"
+  },
+  "exclude": [
+    "**/*.spec.ts",
+    "node_modules",
+    "vendor"
+    "public"
+  ],
+  "compileOnSave": false
+}
+```
+
+3. Finally add `.tsx` to the list of extensions in `config/webpacker.yml`
+and rename your generated `hello_react.js` using react installer
+to `hello_react.tsx` and make it valid typescript and now you can use
+typescript, JSX with React.
+
+
+
+## HTML templates with Typescript and Angular
+
+After you have installed angular using `bundle exec rails webpacker:install:angular`
+you would need to follow these steps to add HTML templates support:
+
+1. Use `yarn` to add html-loader
+
+```bash
+yarn add html-loader
+```
+
+2. Add html-loader to `config/webpack/environment.js`
+
+```js
+environment.loaders.add('html', {
+  test: /\.html$/,
+  use: [{
+    loader: 'html-loader',
+    options: {
+      minimize: true,
+      removeAttributeQuotes: false,
+      caseSensitive: true,
+      customAttrSurround: [ [/#/, /(?:)/], [/\*/, /(?:)/], [/\[?\(?/, /(?:)/] ],
+      customAttrAssign: [ /\)?\]?=/ ]
+    }
+  }]
+})
+```
+
+3. Add `.html` to `config/webpacker.yml`
+
+```yml
+  extensions:
+    - .elm
+    - .coffee
+    - .html
+```
+
+4. Setup a custom `d.ts` definition
+
+```ts
+// app/javascript/hello_angular/html.d.ts
+
+declare module "*.html" {
+  const content: string
+  export default content
+}
+```
+
+5. Add a template.html file relative to `app.component.ts`
+
+```html
+<h1>Hello {{name}}</h1>
+```
+
+6. Import template into `app.component.ts`
+
+```ts
+import { Component } from '@angular/core'
+import templateString from './template.html'
+
+@Component({
+  selector: 'hello-angular',
+  template: templateString
+})
+
+export class AppComponent {
+  name = 'Angular!'
+}
+```
+
+That's all. Voila!

data/docs/webpack-dev-server.md

@@ -0,0 +1,32 @@
+# Webpack Dev Server
+
+
+## HTTPS
+
+If you're using the `webpack-dev-server` in development, you can serve your packs over HTTPS
+by setting the `https` option for `webpack-dev-server` to `true` in `config/webpacker.yml`,
+then start the dev server as usual with `./bin/webpack-dev-server`.
+
+Please note that the `webpack-dev-server` will use a self-signed certificate,
+so your web browser will display a warning/exception upon accessing the page. If you get
+`https://localhost:3035/sockjs-node/info?t=1503127986584 net::ERR_INSECURE_RESPONSE`
+in your console, simply open the link in your browser and accept the SSL exception.
+Now if you refresh your rails view everything should work as expected.
+
+
+## HOT module replacement
+
+Webpacker out-of-the-box supports HMR with `webpack-dev-server` and
+you can toggle it by setting `dev_server/hmr` option inside webpacker.yml.
+
+Checkout this guide for more information:
+
+- https://webpack.js.org/configuration/dev-server/#devserver-hot
+
+To support HMR with React you would need to add `react-hot-loader`. Checkout this guide for
+more information:
+
+- https://gaearon.github.io/react-hot-loader/getstarted/
+
+**Note:** Don't forget to disable `HMR` if you are not running `webpack-dev-server`
+otherwise you will get not found error for stylesheets.

data/docs/webpack.md

@@ -0,0 +1,156 @@
+# Webpack
+
+
+## Configuration
+
+Webpacker gives you a default set of configuration files for test, development and
+production environments in `config/webpack/*.js`. You can configure each individual
+environment in their respective files or configure them all in the base
+`config/webpack/environment.js` file.
+
+By default, you shouldn't have to make any changes to `config/webpack/*.js`
+files since it's all standard production-ready configuration. However,
+if you do need to customize or add a new loader, this is where you would go.
+
+Here is how you can modify webpack configuration:
+
+```js
+// config/webpack/custom.js
+module.exports = {
+  resolve: {
+    alias: {
+      jquery: 'jquery/src/jquery',
+      vue: 'vue/dist/vue.js',
+      React: 'react',
+      ReactDOM: 'react-dom',
+      vue_resource: 'vue-resource/dist/vue-resource',
+    }
+  }
+}
+
+// config/webpack/development.js
+const merge = require('webpack-merge')
+const environment = require('./environment')
+const customConfig = require('./custom')
+
+module.exports = merge(environment.toWebpackConfig(), customConfig)
+```
+
+**Note:** You will have to merge custom config to all env where you want that config
+to be available. In above case, it will be applied to development environment.
+
+
+## Loaders
+
+You can add additional loaders beyond the base set that webpacker provides by
+adding it to your environment. We'll use `json-loader` as an example:
+
+```
+yarn add json-loader
+```
+
+```js
+// config/webpack/environment.js
+const { environment } = require('@rails/webpacker')
+
+environment.loaders.set('json', {
+  test: /\.json$/,
+  use: 'json-loader'
+})
+
+module.exports = environment
+```
+
+Finally add `.json` to the list of extensions in `config/webpacker.yml`. Now if you `import()` any `.json` files inside your javascript
+they will be processed using `json-loader`. Voila!
+
+You can also modify the loaders that webpacker pre-configures for you. We'll update
+the `babel` loader as an example:
+
+```js
+// config/webpack/environment.js
+const { environment } = require('@rails/webpacker')
+
+// Update an option directly
+const babelLoader = environment.loaders.get('babel')
+babelLoader.options.cacheDirectory = false
+
+module.exports = environment
+```
+
+
+## Plugins
+
+The process for adding or modifying webpack plugins is the same as the process
+for loaders above:
+
+```js
+// config/webpack/environment.js
+const { environment } = require('@rails/webpacker')
+const webpack = require('webpack')
+
+// Get a pre-configured plugin
+environment.plugins.get('ExtractText') // Is an ExtractTextPlugin instance
+
+// Add an additional plugin of your choosing : ProvidePlugin
+environment.plugins.set(
+  'Provide',
+  new webpack.ProvidePlugin({
+    $: 'jquery',
+    jQuery: 'jquery',
+    jquery: 'jquery',
+    'window.Tether': 'tether',
+    Popper: ['popper.js', 'default'],
+    ActionCable: 'actioncable',
+    Vue: 'vue',
+    VueResource: 'vue-resource',
+  })
+)
+
+module.exports = environment
+```
+
+
+### Add common chunks
+
+The CommonsChunkPlugin is an opt-in feature that creates a separate file (known as a chunk), consisting of common modules shared between multiple entry points. By separating common modules from bundles, the resulting chunked file can be loaded once initially, and stored in the cache for later use. This results in page speed optimizations as the browser can quickly serve the shared code from the cache, rather than being forced to load a larger bundle whenever a new page is visited.
+
+Add the plugins in `config/webpack/environment.js`:
+
+```js
+const webpack = require('webpack')
+
+environment.plugins.set(
+  'CommonsChunkVendor',
+  new webpack.optimize.CommonsChunkPlugin({
+    name: 'vendor',
+    minChunks: (module) => {
+      // this assumes your vendor imports exist in the node_modules directory
+      return module.context && module.context.indexOf('node_modules') !== -1;
+    }
+  })
+)
+
+environment.plugins.set(
+  'CommonsChunkManifest',
+  new webpack.optimize.CommonsChunkPlugin({
+    name: 'manifest',
+    minChunks: Infinity
+  })
+)
+```
+
+Now, add these files to your `layouts/application.html.erb`:
+
+```erb
+<%# Head %>
+
+<%= javascript_pack_tag "manifest" %>
+<%= javascript_pack_tag "vendor" %>
+
+<%# If importing any styles from node_modules in your JS app %>
+
+<%= stylesheet_pack_tag "vendor" %>
+```
+
+More detailed guides available here: [Webpack guides](https://webpack.js.org/guides/)