webpacker 2.0 → 3.0.0

data/docs/assets.md

@@ -0,0 +1,106 @@
+# Assets
+
+
+Static assets like images and fonts support is enabled out-of-box
+and you can link them into your javascript app code and have them
+compiled automatically.
+
+
+## Import from node modules
+
+You can also import styles from `node_modules` using the following syntax.
+Please note that your styles will always be extracted into `[pack_name].css`:
+
+```sass
+// app/javascript/styles.sass
+// ~ to tell webpack that this is not a relative import:
+
+@import '~@material/animation/mdc-animation'
+@import '~bootstrap/dist/css/bootstrap'
+```
+
+```js
+// Your main app pack
+// app/javascript/packs/app.js
+
+import '../styles'
+```
+
+```erb
+<%# In your views %>
+
+<%= javascript_pack_tag 'app' %>
+<%= stylesheet_pack_tag 'app' %>
+```
+
+
+## Import from sprockets using helpers
+
+It's possible to link to assets that have been precompiled by sprockets. Add the `.erb` extension to your javascript file, then you can use Sprockets' asset helpers:
+
+```erb
+<%# app/javascript/my_pack/example.js.erb %>
+
+<% helpers = ActionController::Base.helpers %>
+var railsImagePath = "<%= helpers.image_path('rails.png') %>"
+```
+
+This is enabled by the `rails-erb-loader` loader rule in `config/webpack/loaders/erb.js`.
+
+
+## Using babel module resolver
+
+You can also use [babel-plugin-module-resolver](https://github.com/tleunen/babel-plugin-module-resolver) to reference assets directly from `app/assets/**`
+
+```bash
+yarn add babel-plugin-module-resolver
+```
+
+Specify the plugin in your `.babelrc` with the custom root or alias. Here's an example:
+
+```json
+{
+  "plugins": [
+    ["module-resolver", {
+      "root": ["./app"],
+      "alias": {
+        "assets": "./assets"
+      }
+    }]
+  ]
+}
+```
+
+And then within your javascript app code:
+
+```js
+// Note: we don't have do any ../../ jazz
+
+import FooImage from 'assets/images/foo-image.png'
+import 'assets/stylesheets/bar'
+```
+
+
+## Link in your Rails views
+
+You can also link `js/images/styles/fonts` used within your js app in views using
+`asset_pack_path` helper. This helper is useful in cases where you just want to
+create a `<link rel="prefetch">` or `<img />` for an asset.
+
+```yml
+app/javascript:
+  - packs
+    - hello_react.js
+  - styles
+    - hello_react.css
+  - images
+    - calendar.png
+```
+
+```erb
+<%= asset_pack_path 'hello_react.css' %>
+<%# => "/packs/hello_react.css" %>
+
+<img src="<%= asset_pack_path 'images/calendar.png' %>" />
+<% # => <img src="/packs/images/calendar.png" /> %>
+```

data/docs/css.md

@@ -0,0 +1,82 @@
+# CSS, SASS and SCSS
+
+
+Webpacker supports importing css, sass and scss files directly into your javascript files.
+
+
+## Import styles into your JS app
+
+```sass
+// app/javascript/hello_react/styles/hello-react.sass
+
+.hello-react
+  padding: 20px
+  font-size: 12px
+```
+
+```js
+// React component example
+// app/javascripts/packs/hello_react.jsx
+
+import React from 'react'
+import helloIcon from '../hello_react/images/icon.png'
+import '../hello_react/styles/hello-react'
+
+const Hello = props => (
+  <div className="hello-react">
+    <img src={helloIcon} alt="hello-icon" />
+    <p>Hello {props.name}!</p>
+  </div>
+)
+```
+
+
+## Link styles from your Rails views
+
+Under the hood webpack uses
+[extract-text-webpack-plugin](https://github.com/webpack-contrib/extract-text-webpack-plugin) plugin to extract all the referenced styles within your app and compile it into
+a separate `[pack_name].css` bundle so that in your view you can use the
+`stylesheet_pack_tag` helper.
+
+```erb
+<%= stylesheet_pack_tag 'hello_react' %>
+```
+
+
+## Add bootstrap
+
+You can use yarn to add bootstrap or any other modules available on npm:
+
+```bash
+yarn add bootstrap
+```
+
+Import Bootstrap and theme (optional) CSS in your app/javascript/packs/app.js file:
+
+```js
+import 'bootstrap/dist/css/bootstrap'
+import 'bootstrap/dist/css/bootstrap-theme'
+```
+
+Or in your app/javascript/app.sass file:
+
+```sass
+// ~ to tell that this is not a relative import
+
+@import '~bootstrap/dist/css/bootstrap'
+@import '~bootstrap/dist/css/bootstrap-theme'
+```
+
+
+## Post-Processing CSS
+
+Webpacker out-of-the-box provides CSS post-processing using
+[postcss-loader](https://github.com/postcss/postcss-loader)
+and the installer sets up a standard `.postcssrc.yml`
+file in your app root with standard plugins.
+
+```yml
+plugins:
+  postcss-smart-import: {}
+  postcss-cssnext: {}
+```

data/docs/deployment.md

@@ -0,0 +1,39 @@
+# Deployment
+
+
+Webpacker hooks up a new `webpacker:compile` task to `assets:precompile`, which gets run whenever you run `assets:precompile`. If you are not using sprockets you
+can manually trigger `bundle exec rails webpacker:compile` during your app deploy.
+
+The `javascript_pack_tag` and `stylesheet_pack_tag` helper method will automatically insert the correct HTML tag for compiled pack. Just like the asset pipeline does it.
+
+By default the output will look like this in different environments:
+
+```html
+  <!-- In development mode -->
+  <script src="/packs/calendar.js"></script>
+  <link rel="stylesheet" media="screen" href="/packs/calendar.css">
+  <!-- In development mode with webpack-dev-server -->
+  <script src="http://localhost:8080/calendar.js"></script>
+  <link rel="stylesheet" media="screen" href="http://localhost:8080/calendar.css">
+  <!-- In production mode -->
+  <script src="/packs/calendar-0bd141f6d9360cf4a7f5.js"></script>
+  <link rel="stylesheet" media="screen" href="/packs/calendar-dc02976b5f94b507e3b6.css">
+```
+
+
+## Heroku
+
+Heroku installs yarn and node by default if you deploy a rails app with
+Webpacker so all you would need to do:
+
+```bash
+heroku create shiny-webpacker-app
+heroku addons:create heroku-postgresql:hobby-dev
+git push heroku master
+```
+
+
+## CDN
+
+Webpacker out-of-the-box provides CDN support using your Rails app `config.action_controller.asset_host` setting. If you already have [CDN](http://guides.rubyonrails.org/asset_pipeline.html#cdns) added in your rails app
+you don't need to do anything extra for webpacker, it just works.

data/docs/env.md

@@ -0,0 +1,62 @@
+# Environment variables
+
+
+Environment variables are supported out of the box in Webpacker. For example if
+you run the Webpack dev server like so:
+```
+FOO=hello BAR=world ./bin/webpack-dev-server
+```
+
+You can then reference these variables in your javascript app code with
+`process.env`:
+
+```js
+console.log(process.env.FOO) // Compiles to console.log("hello")
+```
+
+You may want to store configuration in environment variables via `.env` files,
+similar to the [dotenv Ruby gem](https://github.com/bkeepers/dotenv).
+
+In development, if you use Foreman or [Invoker](http://invoker.codemancers.com)
+to launch the Webpack server, both of these tools have basic support for a
+`.env` file (Invoker also supports `.env.local`), so no further configuration
+is needed.
+
+However, if you run the Webpack server without Foreman/Invoker, or if you
+want more control over what `.env` files to load, you can use the
+[dotenv npm package](https://github.com/motdotla/dotenv). Here is what you could
+do to support a "Ruby-like" dotenv:
+
+```
+yarn add dotenv
+```
+
+```javascript
+// config/webpack/environment.js
+
+...
+const dotenv = require('dotenv');
+
+const dotenvFiles = [
+  `.env.${process.env.NODE_ENV}.local`,
+  '.env.local',
+  `.env.${process.env.NODE_ENV}`,
+  '.env'
+];
+dotenvFiles.forEach((dotenvFile) => {
+  dotenv.config({ path: dotenvFile, silent: true });
+});
+
+module.exports = {
+  ...
+```
+
+**Warning:** using Foreman/Invoker and npm dotenv at the same time can result in
+confusing behavior, in that Foreman/Invoker variables take precedence over
+npm dotenv variables.
+
+If you'd like to pass custom variables to the on demand compiler, use `Webpack::Compiler.env` attribute.
+
+```rb
+Webpacker::Compiler.env['FRONTEND_API_KEY'] = 'your_secret_key'
+```

data/docs/es6.md

@@ -0,0 +1,53 @@
+# 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 `.babelrc` file in your app root, which will work great in most cases
+because of [babel-env-preset](https://github.com/babel/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 [babel polyfill](https://babeljs.io/docs/usage/polyfill/)
+that includes a custom regenerator runtime and core-js.
+
+Don't forget to import `babel-polyfill` in your main entry point like so:
+
+```js
+import "babel-polyfill"
+```
+
+
+## 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.add('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,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.