jetpacker 0.1.0 → 0.2.0

data/docs/es6.md

@@ -0,0 +1,72 @@
+# ES6
+
+## Babel
+
+Webpacker ships with [babel](https://babeljs.io/) - a JavaScript compiler so
+you can use next generation JavaScript, today. The Webpacker installer sets up a
+standard `babel.config.js` file in your app root, which will work great in most cases
+because of [@babel/preset-env](https://github.com/babel/babel/tree/master/packages/babel-preset-env).
+
+Following ES6/7 features are supported out of the box:
+
+* Async/await.
+* Object Rest/Spread Properties.
+* Exponentiation Operator.
+* Dynamic import() - useful for route level code-splitting
+* Class Fields and Static Properties.
+
+We have also included [core-js](https://github.com/zloirock/core-js) to polyfill features in the
+older browsers.
+
+Don't forget to add these lines into your main entry point:
+
+```js
+import "core-js/stable";
+import "regenerator-runtime/runtime";
+```
+
+## Dynamic/Lazy Chunk Loading
+
+For this section, you need Webpack and Webpacker 4. Then enable `SplitChunks` as it is explained in [docs/webpack](webpack.md).
+
+[Dynamic code splitting](https://webpack.js.org/guides/code-splitting#dynamic-imports) enables you to conditionally request/run only the JS that you need. For example, if your site has a `searchBarComponent` on every page, you can reduce the page overhead by deferring the request for the `searchBarComponent` code until after the page has loaded, until the user has scrolled it into view, or until the user has clicked on an element.
+
+```js
+ function loadSearchBarComponent() {
+   return import(/* webpackChunkName: "searchBarComponent" */ './pathTo/searchBarComponent')
+ }
+```
+
+The comment you see above (`/* webpackChunkName */`) is not arbitrary, it is one of webpacks [magic comments](https://webpack.js.org/api/module-methods/#magic-comments). They can be used to fine-tune `import()` with settings such as `defer` or `prefetch`.
+
+**Warning**: You should not attempt to dynamically load anything from your `packs/` folder. Instead, try to make your `pack` scripts a hub from which you dynamically load `non-pack` scripts.
+
+- [Docs for using magic comments](https://webpack.js.org/api/module-methods/#magic-comments)
+- [Docs for configuring `splitChunks` in webpacker](https://github.com/rails/webpacker/blob/master/docs/webpack.md#add-splitchunks-webpack-v4).
+- [Docs for using dynamic `import()`](https://webpack.js.org/guides/code-splitting#dynamic-imports).
+
+## Module import vs require()
+
+While you are free to use `require()` and `module.exports`, we encourage you
+to use `import` and `export` instead since it reads and looks much better.
+
+```js
+import Button from 'react-bootstrap/lib/Button'
+
+// or
+import { Button } from 'react-bootstrap'
+
+class Foo {
+  // code...
+}
+
+export default Foo
+import Foo from './foo'
+```
+
+You can also use named export and import
+
+```js
+export const foo = () => console.log('hello world')
+import { foo } from './foo'
+```

data/docs/folder-structure.md

@@ -0,0 +1,66 @@
+# Folder Structure
+
+
+## Packs a.k.a webpack entries
+
+"Packs" is a special directory made only for webpack entry files so don't put anything
+here that you don't want to link in your views.
+
+
+## Source
+
+You can put your app source under `app/javascript` folder or whatever you have configured
+in `config/webpacker.yml`.
+
+
+## Example
+
+Let's say you're building a calendar app. Your JS app structure could look like this:
+
+```js
+// app/javascript/packs/calendar.js
+
+import 'calendar'
+```
+
+```
+app/javascript/calendar/index.js // gets loaded by import 'calendar'
+app/javascript/calendar/components/grid.jsx
+app/javascript/calendar/styles/grid.sass
+app/javascript/calendar/models/month.js
+```
+
+```erb
+<%# app/views/layouts/application.html.erb %>
+
+<%= javascript_pack_tag 'calendar' %>
+<%= stylesheet_pack_tag 'calendar' %>
+```
+
+But it could also look a million other ways.
+
+
+## Namespacing
+
+You can also namespace your packs using directories similar to a Rails app.
+
+```
+app/javascript/packs/admin/orders.js
+app/javascript/packs/shop/orders.js
+```
+
+and reference them in your views like this:
+
+```erb
+<%# app/views/admin/orders/index.html.erb %>
+
+<%= javascript_pack_tag 'admin/orders' %>
+```
+
+and
+
+```erb
+<%# app/views/shop/orders/index.html.erb %>
+
+<%= javascript_pack_tag 'shop/orders' %>
+```

data/docs/misc.md

@@ -0,0 +1,23 @@
+# How-Tos
+
+
+## Ignoring swap files
+
+If you are using vim or emacs and want to ignore certain files you can add `ignore-loader`:
+
+```
+yarn add ignore-loader
+```
+
+and add `ignore-loader` to `config/webpack/environment.js`
+
+```js
+// ignores vue~ swap files
+const { environment } = require('@rails/webpacker')
+environment.loaders.append('ignore', {
+  test:  /.vue~$/,
+  loader: 'ignore-loader'
+})
+```
+
+And now all files with `.vue~` will be ignored by the webpack compiler.

data/docs/props.md

@@ -0,0 +1,223 @@
+# 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.
+
+
+## Elm
+
+Just like with other implementations, we'll render our data inside a `data`
+attribute:
+
+```erb
+<%= content_tag :div,
+  id: "hello-elm",
+  data: {
+    message: "Hello",
+    name: "David"
+  }.to_json do %>
+<% end %>
+```
+
+We parse the JSON data and pass it to Elm as flags:
+
+```js
+import Elm from '../Main'
+
+document.addEventListener('DOMContentLoaded', () => {
+  const node = document.getElementById('hello-elm')
+  const data = JSON.parse(node.getAttribute('data'))
+  Elm.Main.embed(node, data)
+})
+```
+
+Defining `Flags` as a `type alias`, we instruct Elm to demand flags `message`
+and `name` of type `String` on initialization.
+
+Using `programWithFlags` we bring all the pieces together:
+
+
+```elm
+module Main exposing (..)
+
+import Html exposing (Html, programWithFlags, h1, text)
+import Html.Attributes exposing (style)
+
+
+-- MODEL
+
+
+type alias Flags =
+    { message : String
+    , name : String
+    }
+
+
+type alias Model =
+    { message : String
+    , name : String
+    }
+
+
+type Msg
+    = NoOp
+
+
+
+-- INIT
+
+
+init : Flags -> ( Model, Cmd Msg )
+init flags =
+    let
+        { message, name } =
+            flags
+    in
+        ( Model message name, Cmd.none )
+
+
+
+-- UPDATE
+
+
+update : Msg -> Model -> ( Model, Cmd Msg )
+update msg model =
+    case msg of
+        NoOp ->
+            ( model, Cmd.none )
+
+
+
+-- SUBSCRIPTIONS
+
+
+subscriptions : Model -> Sub Msg
+subscriptions model =
+    Sub.none
+
+
+
+-- VIEW
+
+
+view : Model -> Html Msg
+view model =
+    h1 [ style [ ( "display", "flex" ), ( "justify-content", "center" ) ] ]
+        [ text (model.message ++ ", " ++ model.name ++ "!") ]
+
+
+
+-- MAIN
+
+
+main : Program Flags Model Msg
+main =
+    programWithFlags
+        { view = view
+        , init = init
+        , update = update
+        , subscriptions = subscriptions
+        }
+
+```

data/docs/testing.md

@@ -0,0 +1,137 @@
+# 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.append('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
+```
+
+## Capybara setup for Rails
+Make sure you configure Rails to serve static files from the public directory in the test environment.
+
+```rb
+# config/environments/test.rb
+# Configure public file server for tests with Cache-Control for performance.
+config.public_file_server.enabled = true
+```