jetpacker 0.1.0 → 0.2.0

data/Rakefile

@@ -1,6 +1,11 @@
+# frozen_string_literal: true
 require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require "rake/testtask"
 
-RSpec::Core::RakeTask.new(:spec)
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
 
-task :default => :spec
+task default: :test

data/docs/assets.md

@@ -0,0 +1,119 @@
+# 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 %>
+const 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 `babel.config.js` with the custom root or alias. Here's an example:
+
+```js
+{
+  plugins: [
+    [require("babel-plugin-module-resolver").default, {
+      "root": ["./app"],
+      "alias": {
+        "assets": "./assets"
+      }
+    }]
+  ]
+}
+```
+
+And then within your javascript app code:
+
+```js
+// Note: we don't have to 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` and `image_pack_tag` helpers. These helpers are useful in cases where you just want to
+create a `<link rel="prefetch">` or `<img />` for an asset.
+
+```yml
+app/javascript:
+  - packs
+    - app.js
+  - images
+    - calendar.png
+```
+
+```js
+// app/javascript/packs/app.js (or any of your packs)
+
+// import all image files in a folder:
+require.context('../images', true)
+```
+
+```erb
+<%# Rails view, for example app/views/layouts/application.html.erb %>
+
+<img src="<%= asset_pack_path 'media/images/calendar.png' %>" />
+<% # => <img src="/packs/media/images/calendar-k344a6d59eef8632c9d1.png" /> %>
+
+<%= image_pack_tag 'media/images/calendar.png' %>
+<% # => <img src="/packs/media/images/calendar-k344a6d59eef8632c9d1.png" /> %>
+
+<%# no path resolves to default 'images' folder: %>
+<%= image_pack_tag 'calendar.png' %>
+<% # => <img src="/packs/media/images/calendar-k344a6d59eef8632c9d1.png" /> %>
+```
+
+Note you need to add a `media/` prefix (not `/media/`) to any subfolder structure you might have in `app/javascript`. See more examples in the [tests](https://github.com/rails/webpacker/blob/0b86cadb5ed921e2c1538382e72a236ec30a5d97/test/helper_test.rb#L37).

data/docs/cloud9.md

@@ -0,0 +1,310 @@
+# Webpack dev server and Rails on Cloud9
+
+**Please note that this article is particularly relevant when
+migrating the [`webpacker`] gem from v3.0.1 to v3.0.2, as described in
+the [below](#binstub-versions).**
+
+[**`[Go to tl;dr]`**](#tldr)
+
+## Contents
+
+  - [Context](#context)
+  - [Binstub versions](#binstub-versions)
+  - [Quick solution](#quick-solution)
+  - [Flexible solution](#flexible-solution)
+  - [Sources](#sources)
+  - [Versions](#versions)
+  - [tl;dr](#tldr)
+
+## Context
+
+This article describes how to properly configure
+[`webpack-dev-server`] with [`webpacker`] gem on a [Cloud9] workspace.
+After a preliminary remark about the proper binstub version of the
+`./bin/webpack-dev-server` script, this article presents two ways to
+tackle the task: a simple and [quick solution](#quick-solution), which
+is sufficient if we work alone on a project, and a slightly more
+involved but [flexible approach](#flexible-solution), that can be
+useful when several people might work in the same codebase.
+
+[Cloud9]: https://c9.io
+[`webpack-dev-server`]: https://github.com/webpack/webpack-dev-server
+[`webpacker`]: https://github.com/rails/webpacker
+
+## Binstub versions
+
+A lot of the confusion about the [`webpack-dev-server`] options and
+why they might not be properly taken into account, might be due to an
+outdated version of the `./bin/webpack-dev-server` script. The script
+created by the `rails webpacker:install` task of the [`webpacker`] gem
+v3.0.1 ([source][v3.0.1/lib/install/bin/webpack-dev-server.tt]) is not
+compatible with how v3.0.2 (sic) of the gem handles the
+[`webpack-dev-server`] option flags (see full list of
+[versions](#versions) below), which logically expects the
+corresponding [binstub version][#833] of the script
+([source][v3.0.2/exe/webpack-dev-server]). So please make sure that
+you are using the [correct binstub][v3.0.2/exe/webpack-dev-server]
+(the same applies to [`./bin/webpack`][v3.0.2/exe/webpack]). To be
+fair, the [changelog of v3.0.2] properly mentions the change:
+
+> - Added: Binstubs [#833]
+> - (...)
+> - Removed: Inline CLI args for dev server binstub, use env variables
+  instead
+
+[changelog of v3.0.2]: https://github.com/rails/webpacker/blob/v3.0.2/CHANGELOG.md#302---2017-10-04
+[v3.0.1/lib/install/bin/webpack-dev-server.tt]: https://github.com/rails/webpacker/blob/v3.0.1/lib/install/bin/webpack-dev-server.tt
+[v3.0.2/exe/webpack-dev-server]: https://github.com/rails/webpacker/blob/v3.0.2/exe/webpack-dev-server
+[v3.0.2/exe/webpack]: https://github.com/rails/webpacker/blob/v3.0.2/exe/webpack
+[#833]: https://github.com/rails/webpacker/pull/833/files
+
+## Quick solution
+
+If you are working alone, the easiest way to fix the configuration of
+the [`webpack-dev-server`] is to modify the `development.dev_server`
+entry of the `config/webpacker.yml` file.
+
+### `config/webpacker.yml` file
+
+The `development.dev_server` entry of the `config/webpacker.yml` file
+has to be changed from the following default values:
+
+```yaml
+dev_server:
+  https: false
+  host: localhost
+  port: 3035
+  public: localhost:3035
+  hmr: false
+  # Inline should be set to true if using HMR
+  inline: true
+  overlay: true
+  disable_host_check: true
+  use_local_ip: false
+```
+
+into these custom configuration:
+
+```yaml
+dev_server:
+  https: true
+  host: localhost
+  port: 8082
+  public: your-workspace-name-yourusername.c9users.io:8082
+  hmr: false
+  inline: false
+  overlay: true
+  disable_host_check: true
+  use_local_ip: false
+```
+
+You can obtain the value `your-workspace-name-yourusername.c9users.io`
+for your [Cloud9] workspace with `echo ${C9_HOSTNAME}`.
+
+There are four main differences with the approaches found in the
+mentioned [sources](#sources):
+
+- Some solutions suggested to set the [`host`][devserver-host] option
+  to `your-workspace-name-yourusername.c9users.io`, which required to
+  add a line to the `/etc/hosts` file by running `echo "0.0.0.0
+  ${C9_HOSTNAME}" | sudo tee -a /etc/hosts`. This was only necessary
+  due to restrictions in previous versions of [`webpacker`] and how
+  the value of the [`public`][devserver-public] setting was
+  calculated. Currently it is [no longer necessary][pr-comment-hosts]
+  to modify the `/etc/hosts` file because the [`host`][devserver-host]
+  setting can be kept as `localhost`.
+
+[pr-comment-hosts]: https://github.com/rails/webpacker/pull/1033#pullrequestreview-78992024
+
+- Some solutions stressed the need to set the
+  [`https`][devserver-https] option to `false` but this failed with
+  `net::ERR_ABORTED` in the browser console and raised the following
+  exception in the server when the client tried to get the
+  JavaScript sources:
+
+  ```
+  #<OpenSSL::SSL::SSLError: SSL_connect SYSCALL returned=5 errno=0 state=unknown state>
+  ```
+
+  Setting `https: true` removes the issue.
+
+- By leaving the [`inline`][devserver-inline] option to the default
+  `false` value, the live compilation still works but the browser
+  console constantly reports the following error:
+
+  ```
+  Failed to load https://your-workspace-name-yourusername.c9users.io:8082/sockjs-node/info?t=1511016561187: No 'Access-Control-Allow-Origin' header is present on the requested resource.
+  Origin 'https://your-workspace-name-yourusername.c9users.io' is therefore not allowed access. The response had HTTP status code 503.
+  ```
+
+  Setting `inline: false` removes the issue.
+
+
+- None of the solutions suggested to set the
+  [`public`][devserver-public] option in the `config/webpacker.yml`
+  file and some suggested to pass it to the `webpack-dev-server`
+  command line. By setting it in the configuration file we don't need
+  to care about it in the terminal.
+
+[devserver-host]: https://webpack.js.org/configuration/dev-server/#devserver-host
+[devserver-https]: https://webpack.js.org/configuration/dev-server/#devserver-https
+[devserver-inline]: https://webpack.js.org/configuration/dev-server/#devserver-inline
+[devserver-public]: https://webpack.js.org/configuration/dev-server/#devserver-public
+
+With this configuration, running as usual `./bin/webpack-dev-server`
+in one terminal and `./bin/rails s -b $IP -p $PORT` in another should
+work.
+
+## Flexible solution
+
+The previous solution is useful and fast to implement, but if you are
+working with other people on the same repo it can be tricky to
+maintain the proper configuration in the `config/webpacker.yml` file.
+Moreover, the hostname of your [Cloud9] workspace is hardcoded, so
+that the configuration is not portable.
+
+A hint about another way to configure the `webpack-dev-server` can be
+found in the [README of this repo][`webpacker` documentation]:
+
+> You can use environment variables as options supported by
+> webpack-dev-server in the form `WEBPACKER_DEV_SERVER_<OPTION>`.
+> Please note that these environment variables will always take
+> precedence over the ones already set in the configuration file.
+
+Note that when the configuration of the [`webpack-dev-server`] is
+tweaked with ENV variables, those same values _have to be passed_ to
+the `rails server` process as well in order to let it use the _same_
+configuration.
+
+Taking that into account, a flexible solution can be implemented using
+[`foreman`] with the following `Procfile.dev`:
+
+[`foreman`]: https://github.com/ddollar/foreman
+
+```Procfile
+web:        ./bin/rails server -b ${RAILS_SERVER_BINDING:-localhost} -p ${RAILS_SERVER_PORT:-3000}
+webpacker:  ./bin/webpack-dev-server
+```
+
+and this `bin/start` script:
+
+```bash
+#!/bin/bash
+
+# Immediately exit script on first error
+set -e -o pipefail
+
+APP_ROOT_FOLDER="$( cd "$( dirname "${BASH_SOURCE[0]}" )/.." && pwd )"
+cd "${APP_ROOT_FOLDER}"
+
+if [ -n "${C9_USER}" ]; then
+  # We are in a Cloud9 machine
+
+  # Make sure that Postgres is running
+  sudo service postgresql status || sudo service postgresql start
+
+  # Adapt the configuration of the webpack-dev-server
+  export APP_DOMAIN="${C9_HOSTNAME}"
+  export RAILS_SERVER_BINDING='0.0.0.0'
+  export RAILS_SERVER_PORT='8080'
+  export WEBPACKER_DEV_SERVER_PORT='8082'
+  export WEBPACKER_DEV_SERVER_HTTPS='true'
+  export WEBPACKER_DEV_SERVER_HOST="localhost"
+  export WEBPACKER_DEV_SERVER_PUBLIC="${C9_HOSTNAME}:${WEBPACKER_DEV_SERVER_PORT}"
+  export WEBPACKER_DEV_SERVER_HMR='false'
+  export WEBPACKER_DEV_SERVER_INLINE='false'
+  export WEBPACKER_DEV_SERVER_OVERLAY='true'
+  export WEBPACKER_DEV_SERVER_DISABLE_HOST_CHECK='true'
+  export WEBPACKER_DEV_SERVER_USE_LOCAL_IP='false'
+fi
+
+foreman start -f Procfile.dev
+```
+
+With these two scripts in place, the application can always be started
+by running `bin/start`, in both [Cloud9] and other systems. The
+trick is that by exporting the `WEBPACKER_DEV_SERVER_*` variables
+before calling `foreman start`, we make sure that those values are
+available to both `webpack-dev-server` and `rails server` processes.
+
+## Sources
+
+- ["Webpack dev server and Rails on Cloud9"][original-article] (the
+  original source for the present article, inspired by this
+  [comment][original-comment])
+- ["Making Webpacker run on Cloud 9"] (GitHub issue)
+- ["Anyone here got webpack-dev-server to work on Cloud 9?"] (GitHub issue)
+- [`webpacker` documentation]
+- [`webpacker/dev_server.rb` code]
+- [`webpack-dev-server` documentation]
+- ["Using Rails With Webpack in Cloud 9"] (blog article)
+
+[original-article]: http://rbf.io/en/blog/2017/11/18/webpack-dev-server-and-rails-on-cloud9/
+[original-comment]: https://github.com/rails/webpacker/issues/176#issuecomment-345532309
+["Making Webpacker run on Cloud 9"]: https://github.com/rails/webpacker/issues/176
+["Anyone here got webpack-dev-server to work on Cloud 9?"]: https://github.com/webpack/webpack-dev-server/issues/230
+[`webpacker` documentation]: https://github.com/rails/webpacker/tree/v3.0.2#development
+[`webpacker/dev_server.rb` code]: https://github.com/rails/webpacker/blob/v3.0.2/lib/webpacker/dev_server.rb#L55
+[`webpack-dev-server` documentation]: https://webpack.js.org/configuration/dev-server/
+["Using Rails With Webpack in Cloud 9"]: http://aalvarez.me/blog/posts/using-rails-with-webpack-in-cloud-9.html
+
+## Versions
+
+Since things in this ecosystem move fast, it's important to mention the
+versions of the world for which this documentation is relevant:
+
+```shell
+$ egrep '^    ?(ruby|webpacker|rails) ' Gemfile.lock
+    rails (5.1.4)
+    webpacker (3.0.2)
+  ruby 2.4.2p198
+
+$ yarn versions
+yarn versions v1.1.0
+{ http_parser: '2.7.0',
+  node: '8.5.0',
+  v8: '6.0.287.53',
+  uv: '1.14.1',
+  zlib: '1.2.11',
+  ares: '1.10.1-DEV',
+  modules: '57',
+  nghttp2: '1.25.0',
+  openssl: '1.0.2l',
+  icu: '59.1',
+  unicode: '9.0',
+  cldr: '31.0.1',
+  tz: '2017b' }
+
+$ cat /etc/os-release | head -6
+NAME="Ubuntu"
+VERSION="14.04.5 LTS, Trusty Tahr"
+ID=ubuntu
+ID_LIKE=debian
+PRETTY_NAME="Ubuntu 14.04.5 LTS"
+VERSION_ID="14.04"
+```
+
+Everything was tested using Chrome Version 62.
+
+## tl;dr
+
+1. Make sure that you are running the [proper binstub
+   version](#binstub-versions) of `./bin/webpack-dev-server`.
+
+1. Change the `development.dev_server` entry `config/webpacker.yml` file into:
+
+    ```yaml
+    dev_server:
+      https: true
+      host: localhost
+      port: 8082
+      public: your-workspace-name-yourusername.c9users.io:8082
+      hmr: false
+      inline: false
+      overlay: true
+      disable_host_check: true
+      use_local_ip: false
+    ```
+
+1. Now running as usual `./bin/webpack-dev-server` in one terminal and
+   `./bin/rails s -b $IP -p $PORT` in another should work as expected.

data/docs/css.md

@@ -0,0 +1,253 @@
+# CSS, Sass and SCSS
+
+
+Webpacker supports importing CSS, Sass and SCSS files directly into your JavaScript files.
+
+Importing and loading styles is a two step process:
+
+1. You need to tell webpack which file(s) it has to compile and know how to load
+  
+   When you do `import '../scss/application.scss'`, you're telling webpack to include `application.scss` in the build. This does not mean it's going to be compiled into your javascript, only that webpack now compiles and knows how to load this file. (How that file compilation is handled is depending on how your loaders (`css-loader`, `sass-loader`, `file-loader`, etc.) are configured.)
+
+2. You need to load those files in your views
+
+   In order to have styles load in production, you need to include `stylesheet_pack_tag` with the same name as the javascript file that imports the styles.
+
+   When you do `<%= stylesheet_pack_tag 'application' %>`, that's a run-time inclusion from Rails, where Rails gets the correct "asset path" to that file from webpack.
+
+
+## Import global 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/javascript/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>
+)
+```
+
+## Import scoped styles into your JS app
+
+Stylesheets that end with `.module.*` are treated as [CSS Modules](https://github.com/css-modules/css-modules).
+
+```sass
+// app/javascript/hello_react/styles/hello-react.module.sass
+
+.helloReact
+  padding: 20px
+  font-size: 12px
+```
+
+```js
+// React component example
+// app/javascript/packs/hello_react.jsx
+
+import React from 'react'
+import helloIcon from '../hello_react/images/icon.png'
+import styles from '../hello_react/styles/hello-react'
+
+const Hello = props => (
+  <div className={styles.helloReact}>
+    <img src={helloIcon} alt="hello-icon" />
+    <p>Hello {props.name}!</p>
+  </div>
+)
+```
+
+**Note:** Declared class is referenced as object property in JavaScript.
+
+## Import scoped styles into your TypeScript app
+
+Using CSS modules with a TypeScript application requires a few differences from a JavaScript app. The CSS / Sass files are the same:
+
+```sass
+// app/javascript/hello_react/styles/hello-react.module.sass
+
+.helloReact
+  padding: 20px
+  font-size: 12px
+```
+
+There must also be a type definition file for these styles:
+
+```typescript
+export const helloReact: string;
+```
+
+You can then import the styles like this:
+
+```typescript
+// React component example
+// app/javascripts/packs/hello_react.tsx
+
+import React from 'react'
+import helloIcon from '../hello_react/images/icon.png'
+import * as styles from '../hello_react/styles/hello-react.module.sass'
+
+const Hello = props => (
+  <div className={styles.helloReact}>
+    <img src={helloIcon} alt="hello-icon" />
+    <p>Hello {props.name}!</p>
+  </div>
+)
+```
+
+You can automatically generate type definitions for the styles by installing the `typed-scss-modules` as a development dependency:
+
+```
+yarn add typed-scss-modules --dev
+```
+
+Then by adding these lines to your `package.json`:
+
+```
+"scripts": {
+  "gen-typings": "yarn run tsm app/javascript/**/*.sass",
+  "watch-typings": "yarn run tsm app/javascript/**/*.sass -w"
+},
+```
+
+You can generate the typings for the stylesheet by running the command `yarn gen-typings` when you've finished writing CSS, or run `yarn watch-typings` to have it automatically generate them as you go.
+
+
+## Link styles from your Rails views
+
+Under the hood webpack uses
+[mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-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' %>
+```
+
+Webpacker emits css files only if `extract_css` is set to true in webpacker.yml otherwise `stylesheet_pack_tag` returns nil.
+
+## 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 `postcss.config.js`
+file in your app root with standard plugins.
+
+```js
+module.exports = {
+  plugins: [
+    require('postcss-import'),
+    require('postcss-flexbugs-fixes'),
+    require('postcss-preset-env')({
+      autoprefixer: {
+        flexbox: 'no-2009'
+      },
+      stage: 3
+    })
+  ]
+}
+```
+
+## Using CSS with [vue-loader](https://github.com/vuejs/vue-loader)
+
+Vue templates require loading the stylesheet in your application in
+order for CSS to work.  This is in addition to loading the JavaScript
+file for the entry point.  Loading the stylesheet will also load the
+CSS for any nested components.
+
+```erb
+<%= stylesheet_pack_tag 'hello_vue' %>
+<%= javascript_pack_tag 'hello_vue' %>
+```
+
+## Resolve url loader
+
+Since `Sass/libsass` does not provide url rewriting, all linked assets must be relative to the output. Add the missing url rewriting using the resolve-url-loader. Place it directly after the sass-loader in the loader chain.
+
+
+```bash
+yarn add resolve-url-loader
+```
+
+```js
+// webpack/environment.js
+const { environment } = require('@rails/webpacker')
+
+// resolve-url-loader must be used before sass-loader
+environment.loaders.get('sass').use.splice(-1, 0, {
+  loader: 'resolve-url-loader'
+});
+
+module.exports = environment
+```
+
+## Working with TypeScript
+
+In order to get CSS to work with typescript you have two options.
+You can either use `require` to bypass typescript special `import`.
+
+```ts
+const styles = require('../hello_react/styles/hello-react');
+```
+You may also use the package [typings-for-css-modules-loader](https://github.com/Jimdo/typings-for-css-modules-loader) instead of `css-loader` to automatically generate typescript `.d.ts` files in order to help resolve any css/scss styles. To do that:
+
+```js
+// app/javascript/packs/hello_react.jsx
+import * as styles from '../hello_react.styles/hello-react.module.scss';
+```
+
+```bash
+yarn add --dev typings-for-css-modules-loader
+```
+
+```js
+// webpack/environment.js
+const { environment } = require('@rails/webpacker')
+
+// replace css-loader with typings-for-css-modules-loader
+environment.loaders.get('moduleSass').use = environment.loaders.get('moduleSass').use.map((u) => {
+  if(u.loader == 'css-loader') {
+    return { ...u, loader: 'typings-for-css-modules-loader' };
+  } else {
+    return u;
+  }
+});
+```