webpacker-jets 3.2.100

data/docs/testing.md

@@ -0,0 +1,128 @@
+# Testing
+
+## Karma setup for Typescript
+
+Webpacker does not setup `Karma` by default, so you've to manually install it along with its dependencies as per your need. Following things marked as optional can be used to fancify the test results (Recommended).
+
+```js
+// package.json
+"scripts": {
+  "test": "NODE_ENV=test karma start"
+},
+"dependencies": {
+  "typescript": "^2.5.2",
+  "ts-loader": "^2.3.7"
+},
+"devDependencies": {
+  "karma": "^1.7.1",
+  "karma-webpack": "^2.0.4",
+  "karma-chrome-launcher": "^2.2.0",
+  "karma-jquery": "^0.2.2",
+  "karma-jasmine": "^1.1.0",
+  "karma-jasmine-jquery": "^0.1.1",
+  "jasmine-core": "^2.8.0",
+  [optional] "karma-coverage": "^1.1.1",
+  [optional] "karma-coverage-istanbul-reporter": "^1.3.0",
+  [optional] "karma-spec-reporter": "0.0.31",
+  [optional] "istanbul-instrumenter-loader": "^3.0.0",
+}
+```
+
+It is beneficial to use the same webpack configuration file (generated by webpacker) in Karma configuration to avoid redundancy. Following line tells Karma not to write transpiled source files onto filesystem while testing to avoid `Error: EACCES: permission denied, mkdir '/_karma_webpack_' ` error. Then inject a new rule a.k.a. loader in the existing ones (needed only if you have installed `istanbul-instrumenter-loader`) to generate a coverage report under `/coverage` directory.
+
+```js
+// config/webpack/test.js
+const environment = require('./environment')
+environment.plugins.get('Manifest').opts.writeToFileEmit = process.env.NODE_ENV !== 'test'
+environment.loaders.set('istanbul-instrumenter', {
+  test: /\.ts$/,
+  enforce: "post",
+  loader: "istanbul-instrumenter-loader",
+  query: {
+    esModules: true
+  },
+  exclude: ["node_modules", /\.test\.ts$/]
+}) /* optional */
+module.exports = environment.toWebpackConfig()
+```
+
+Finally, update `karma.conf.js` to read the same `test.js` file mentioned above. Rest of the things are mandatory (few marked as optional wherever appropriate).
+
+```js
+// karma.conf.js
+const webpackConfig = require('./config/webpack/test.js')
+module.exports = function(config) {
+  config.set({
+    basePath: "",
+    frameworks: ["jquery-3.2.1", "jasmine-jquery", "jasmine"],
+    plugins: [
+      "karma-jquery",
+      "karma-jasmine-jquery",
+      "karma-jasmine",
+      "karma-webpack",
+      "karma-chrome-launcher",
+      "karma-coverage-istanbul-reporter" /* optional */,
+      "karma-spec-reporter" /* optional */
+    ],
+    files: [ "/* add spec files */" ],
+    exclude: [],
+    webpack: webpackConfig,
+    preprocessors: {"/* add spec files */" : ["webpack"]},
+    mime: { "text/x-typescript": ["ts"] },
+    reporters: ["progress", "coverage-istanbul" /* optional */],
+    coverageIstanbulReporter: {
+      reports: [ 'html', 'lcovonly', 'text-summary' ],
+      fixWebpackSourcePaths: true
+    } /* optional */,
+    port: 9876,
+    colors: true,
+    logLevel: config.LOG_INFO,
+    autoWatch: true,
+    browsers: ["Chrome"],
+    singleRun: true
+  });
+};
+```
+
+## 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,119 @@
+# 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 `jets 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 `jets 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`.
+
+## Running Elm on Continuous Integration (CI) services such as CircleCI, CodeShip, Travis CI
+
+If your tests are timing out or erroring on CI it is likely that you are experiencing the slow Elm compilation issue described here: [elm-compiler issue #1473](https://github.com/elm-lang/elm-compiler/issues/1473)
+
+The issue is related to CPU count exposed by the underlying service. The basic solution involves using [libsysconfcpus](https://github.com/obmarg/libsysconfcpus) to change the reported CPU count.
+
+Basic fix involves:
+
+```bash
+# install sysconfcpus on CI
+git clone https://github.com/obmarg/libsysconfcpus.git $HOME/dependencies/libsysconfcpus
+cd libsysconfcpus
+.configure --prefix=$HOME/dependencies/sysconfcpus
+make && make install
+
+# use sysconfcpus with elm-make
+mv $HOME/your_rails_app/node_modules/.bin/elm-make $HOME/your_rails_app/node_modules/.bin/elm-make-old
+printf "#\041/bin/bash\n\necho \"Running elm-make with sysconfcpus -n 2\"\n\n$HOME/dependencies/sysconfcpus/bin/sysconfcpus -n 2 $HOME/your_rails_app/node_modules/.bin/elm-make-old \"\$@\"" > $HOME/your_rails_app/node_modules/.bin/elm-make
+chmod +x $HOME/your_rails_app/node_modules/.bin/elm-make
+```
+
+## Rake assets:precompile fails. ExecJS::RuntimeError
+This error occurs because you are trying to uglify a pack that's already been minified by Webpacker. To avoid this conflict and prevent appearing of ExecJS::RuntimeError error, you will need to disable uglifier from Rails config:
+
+```ruby
+// production.rb
+# From
+
+Rails.application.config.assets.js_compressor = :uglifier
+
+# To
+
+#Rails.application.config.assets.js_compressor = :uglifier
+
+```
+
+### Angular: WARNING in ./node_modules/@angular/core/esm5/core.js, Critical dependency: the request of a dependency is an expression
+
+To silent these warnings, please update `config/webpack/environment.js`
+
+```js
+// environment.js
+const webpack = require('webpack')
+const { resolve } = require('path')
+const { environment, config } = require('@rails/webpacker')
+
+environment.plugins.set('ContextReplacement',
+  new webpack.ContextReplacementPlugin(
+    /angular(\\|\/)core(\\|\/)(@angular|esm5)/,
+    resolve(config.source_path)
+  )
+)
+```

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 `jets 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.set('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,92 @@
+# 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.
+
+
+## Nginx
+
+If you use Nginx in development to proxy requests to your Rails server from
+another domain, like `myapp.dev`, the Webpacker middleware will be able to
+forward requests for "packs" to the webpack dev server.
+
+If you're using `inline` mode behing Nginx, you may also need to provide the
+hostname to webpack dev server so it can initiate the websocket connection for
+live reloading ([Webpack
+docs](https://webpack.js.org/configuration/dev-server/#devserver-public)).
+
+To do so, set the `public` option in `config/webpacker.yml`:
+
+```yaml
+development:
+  # ...
+  dev_server:
+    # ...
+    public: myapp.dev
+```
+
+You may also need to add the following location block to your local Nginx server
+configuration for your Rails app.
+
+```
+server {
+    listen 80;
+    server_name myapp.dev
+
+    # Proxy webpack dev server websocket requests
+    location /sockjs-node {
+        proxy_redirect off;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_pass http://127.0.0.1:3035; # change to match your webpack-dev-server host
+    }
+
+    # ...
+}
+```
+
+## Customizing Logging
+
+By default, the dev server will display a colored progress notification while
+your code is being compiled.  (Under the hood, we are using `webpack-dev-server
+--progress --color`).  However, this might cause issues if you don't use
+`foreman` and/or try to log webpack-dev-server's output to a file.  You can
+disable this stylized output by adding `pretty: false` to your `dev_server`
+config:
+
+```yaml
+development:
+  # ...
+  dev_server:
+    # ...
+    pretty: false
+```