webpacker 6.0.0.beta.2 → 6.0.0.pre.1

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](/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/integrations.md

@@ -0,0 +1,220 @@
+# Integrations
+
+Webpacker ships with basic out-of-the-box integration for React, Angular, Vue and Elm.
+You can see a list of available commands/tasks by running `bundle exec rails webpacker`:
+
+## React
+
+To use Webpacker with [React](https://facebook.github.io/react/), create a
+new Rails 5.1+ app using `--webpack=react` option:
+
+```bash
+# Rails 5.1+
+rails new myapp --webpack=react
+```
+
+(or run `bundle exec rails webpacker:install:react` in an existing Rails app already
+setup with Webpacker).
+
+The installer will add all relevant dependencies using Yarn, changes
+to the configuration files, and an example React component to your
+project in `app/javascript/packs` so that you can experiment with React right away.
+
+
+## Angular with TypeScript
+
+To use Webpacker with [Angular](https://angular.io/), create a
+new Rails 5.1+ app using `--webpack=angular` option:
+
+```bash
+# Rails 5.1+
+rails new myapp --webpack=angular
+```
+
+(or run `bundle exec rails webpacker:install:angular` on a Rails app already
+setup with Webpacker).
+
+The installer will add the TypeScript and Angular core libraries using Yarn alongside
+a few changes to the configuration files. An example component written in
+TypeScript will also be added to your project in `app/javascript` so that
+you can experiment with Angular right away.
+
+By default, Angular uses a JIT compiler for development environment. This
+compiler is not compatible with restrictive CSP (Content Security
+Policy) environments like Rails 5.2+. You can use Angular AOT compiler
+in development with the [@ngtools/webpack](https://www.npmjs.com/package/@ngtools/webpack#usage) plugin.
+
+Alternatively if you're using Rails 5.2+ you can enable `unsafe-eval` rule for your
+development environment. This can be done in the `config/initializers/content_security_policy.rb`
+with the following code:
+
+```ruby
+Rails.application.config.content_security_policy do |policy|
+  if Rails.env.development?
+    policy.script_src :self, :https, :unsafe_eval
+  else
+    policy.script_src :self, :https
+  end
+end
+```
+
+
+## Vue
+
+To use Webpacker with [Vue](https://vuejs.org/), create a
+new Rails 5.1+ app using `--webpack=vue` option:
+
+```bash
+# Rails 5.1+
+rails new myapp --webpack=vue
+```
+(or run `bundle exec rails webpacker:install:vue` on a Rails app already setup with Webpacker).
+
+The installer will add Vue and its required libraries using Yarn alongside
+automatically applying changes needed to the configuration files. An example component will
+be added to your project in `app/javascript` so that you can experiment with Vue right away.
+
+If you're using Rails 5.2+ you'll need to enable `unsafe-eval` rule for your development environment.
+This can be done in the `config/initializers/content_security_policy.rb` with the following
+configuration:
+
+```ruby
+Rails.application.config.content_security_policy do |policy|
+  if Rails.env.development?
+    policy.script_src :self, :https, :unsafe_eval
+  else
+    policy.script_src :self, :https
+  end
+end
+```
+You can read more about this in the [Vue docs](https://vuejs.org/v2/guide/installation.html#CSP-environments).
+
+### Lazy loading integration
+
+See [docs/es6](es6.md) to know more about Webpack and Webpacker configuration.
+
+For instance, you can lazy load Vue JS components:
+
+Before:
+```js
+import Vue from 'vue'
+import { VCard } from 'vuetify/lib'
+
+Vue.component('VCard', VCard)
+```
+
+After:
+```js
+import Vue from 'vue'
+
+// With destructuring assignment
+Vue.component('VCard', import('vuetify/lib').then(({ VCard }) => VCard)
+
+// Or without destructuring assignment
+Vue.component('OtherComponent', () => import('./OtherComponent'))
+```
+
+You can use it in a Single File Component as well:
+
+```html
+<template>
+  ...
+</template>
+
+<script>
+export default {
+  components: {
+    OtherComponent: () => import('./OtherComponent')
+  }
+}
+</script>
+```
+
+By wrapping the import function into an arrow function, Vue will execute it only when it gets requested, loading the module in that moment.
+
+##### Automatic registration
+
+```js
+/**
+ * The following block of code may be used to automatically register your
+ * Vue components. It will recursively scan this directory for the Vue
+ * components and automatically register them with their "basename".
+ *
+ * Eg. ./components/OtherComponent.vue -> <other-component></other-component>
+ * Eg. ./UI/ButtonComponent.vue -> <button-component></button-component>
+ */
+
+const files = require.context('./', true, /\.vue$/i)
+files.keys().map(key => {
+  const component = key.split('/').pop().split('.')[0]
+
+  // With Lazy Loading
+  Vue.component(component, () => import(`${key}`))
+
+  // Or without Lazy Loading
+  Vue.component(component, files(key).default)
+})
+```
+
+## Elm
+
+To use Webpacker with [Elm](http://elm-lang.org), create a
+new Rails 5.1+ app using `--webpack=elm` option:
+
+```
+# Rails 5.1+
+rails new myapp --webpack=elm
+```
+
+(or run `bundle exec rails webpacker:install:elm` on a Rails app already setup with Webpacker).
+
+The Elm library and its core packages will be added via Yarn and Elm.
+An example `Main.elm` app will also be added to your project in `app/javascript`
+so that you can experiment with Elm right away.
+
+## Svelte
+
+To use Webpacker with [Svelte](https://svelte.dev), create a
+new Rails 5.1+ app using `--webpack=svelte` option:
+
+```
+# Rails 5.1+
+rails new myapp --webpack=svelte
+```
+
+(or run `bundle exec rails webpacker:install:svelte` on a Rails app already setup with Webpacker).
+
+Please play with the [Svelte Tutorial](https://svelte.dev/tutorial/basics) or learn more about its API at https://svelte.dev/docs
+
+## Stimulus
+
+To use Webpacker with [Stimulus](http://stimulusjs.org), create a
+new Rails 5.1+ app using `--webpack=stimulus` option:
+
+```
+# Rails 5.1+
+rails new myapp --webpack=stimulus
+```
+
+(or run `bundle exec rails webpacker:install:stimulus` on a Rails app already setup with Webpacker).
+
+Please read [The Stimulus Handbook](https://stimulusjs.org/handbook/introduction) or learn more about its source code at https://github.com/stimulusjs/stimulus
+
+## CoffeeScript
+
+To add [CoffeeScript](http://coffeescript.org/) support,
+run `bundle exec rails webpacker:install:coffee` on a Rails app already
+setup with Webpacker.
+
+An example `hello_coffee.coffee` file will also be added to your project
+in `app/javascript/packs` so that you can experiment with CoffeeScript right away.
+
+## Erb
+
+To add [Erb](https://apidock.com/ruby/ERB) support in your JS templates,
+run `bundle exec rails webpacker:install:erb` on a Rails app already
+setup with Webpacker and add extension 'erb' on file `config/webpacker.yml`.
+
+An example `hello_erb.js.erb` file will also be added to your project
+in `app/javascript/packs` so that you can experiment with Erb-flavoured
+javascript right away.

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,187 @@
+# Props
+
+How do you pass props from your view to your JavaScript component? Here you go.
+
+## React
+See [docs/react.md](./react.md#props-hydration-and-server-side-rendering-ssr).
+
+## 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
+        }
+
+```