README.md in webpacker-6.0.0.rc.5 vs README.md in webpacker-6.0.0.rc.6
- old
+ new
@@ -9,11 +9,11 @@
[](https://rubygems.org/gems/webpacker)
Webpacker makes it easy to use the JavaScript pre-processor and bundler
[Webpack v5](https://webpack.js.org/)
to manage application-like JavaScript in Rails. It can coexist with the asset pipeline,
-leaving Webpack responsible solely for app-like JavaScript, or it can be used exclusively, making it also responsible for images, fronts, and CSS as well.
+leaving Webpack responsible solely for app-like JavaScript, or it can be used exclusively, making it also responsible for images, fonts, and CSS.
**NOTE:** The master branch now hosts the code for v6.x.x. Please refer to [5-x-stable](https://github.com/rails/webpacker/tree/5-x-stable) branch for 5.x documentation.
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
@@ -76,14 +76,14 @@
- TypeScript
- React
## Installation
-You can configure a new Rails application with Webpacker right from the start using the `--webpack` option:
+You can configure a new Rails application with Webpacker right from the start using the `-j webpack` option:
```bash
-rails new myapp --webpack
+rails new myapp -j webpack
```
Or you can add it later by changing your `Gemfile`:
```ruby
@@ -111,15 +111,14 @@
### Usage
Once installed, you can start writing modern ES6-flavored JavaScript apps right away:
```yml
-app/packs:
- ├── entrypoints:
- │ # Only Webpack entry files here
- │ └── application.js
- │ └── application.css
+app/javascript:
+ # Only Webpack entry files here
+ └── application.js
+ └── application.css
└── src:
│ └── my_component.js
└── stylesheets:
│ └── my_styles.css
└── images:
@@ -137,17 +136,17 @@
packs with the chunks in your view, which creates html tags for all the chunks.
The result looks like this:
```erb
-<%= javascript_pack_tag 'calendar', 'map' %>
+<%= javascript_pack_tag 'calendar', 'map', 'data-turbolinks-track': 'reload' %>
-<script src="/packs/vendor-16838bab065ae1e314.js" data-turbolinks-track="reload"></script>
-<script src="/packs/calendar~runtime-16838bab065ae1e314.js" data-turbolinks-track="reload"></script>
-<script src="/packs/calendar-1016838bab065ae1e314.js" data-turbolinks-track="reload"></script>
-<script src="/packs/map~runtime-16838bab065ae1e314.js" data-turbolinks-track="reload"></script>
-<script src="/packs/map-16838bab065ae1e314.js" data-turbolinks-track="reload"></script>
+<script src="/packs/vendor-16838bab065ae1e314.js" data-turbolinks-track="reload" defer></script>
+<script src="/packs/calendar~runtime-16838bab065ae1e314.js" data-turbolinks-track="reload" defer></script>
+<script src="/packs/calendar-1016838bab065ae1e314.js" data-turbolinks-track="reload" defer"></script>
+<script src="/packs/map~runtime-16838bab065ae1e314.js" data-turbolinks-track="reload" defer></script>
+<script src="/packs/map-16838bab065ae1e314.js" data-turbolinks-track="reload" defer></script>
```
**Important:** Pass all your pack names as multiple arguments, not multiple calls, when using `javascript_pack_tag` and the **`stylesheet_pack_tag`. Otherwise, you will get duplicated chunks on the page. Be especially careful if you might be calling these view helpers from your view, partials, and the layout for a page. You will need some logic to ensure you call the helpers only once with multiple arguments.
```erb
@@ -188,34 +187,44 @@
```css
.foo {
background-image: url('../images/logo.svg')
}
```
+##### Defer for `javascript_pack_tag`
+Note, the default of "defer" for the `javascript_pack_tag`. You can override that to `false`. If you expose jquery globally with `expose-loader,` by using `import $ from "expose-loader?exposes=$,jQuery!jquery"` in your `app/packs/entrypoints/application.js`, pass the option `defer: false` to your `javascript_pack_tag`.
#### Server-Side Rendering (SSR)
-Note, if you are using server-side rendering of JavaScript with dynamic code-spliting, as is often done with extensions to Webpacker, like [React on Rails](https://github.com/shakacode/react_on_rails), your JavaScript should create the link prefetch HTML tags that you will use, so you won't need to use to `asset_pack_path` in those circumstances.
+Note, if you are using server-side rendering of JavaScript with dynamic code-splitting, as is often done with extensions to Webpacker, like [React on Rails](https://github.com/shakacode/react_on_rails), your JavaScript should create the link prefetch HTML tags that you will use, so you won't need to use to `asset_pack_path` in those circumstances.
**Note:** In order for your styles or static assets files to be available in your view, you would need to link them in your "pack" or entry file. Otherwise, Webpack won't know to package up those files.
-
### Development
Webpacker ships with two binstubs: `./bin/webpack` and `./bin/webpack-dev-server`. Both are thin wrappers around the standard `webpack.js` and `webpack-dev-server.js` executables to ensure that the right configuration files and environmental variables are loaded based on your environment.
In development, Webpacker compiles on demand rather than upfront by default. This happens when you refer to any of the pack assets using the Webpacker helper methods. This means that you don't have to run any separate processes. Compilation errors are logged to the standard Rails log. However, this auto-compilation happens when a web request is made that requires an updated webpack build, not when files change. Thus, that can be painfully slow for front-end development in this default way. Instead, you should either run the `bin/webpack --watch` or run `./bin/webpack-dev-server`
-If you want to use live code reloading, or you have enough JavaScript that on-demand compilation is too slow, you'll need to run `./bin/webpack-dev-server` or `ruby ./bin/webpack-dev-server`. Windows users will need to run these commands in a terminal separate from `bundle exec rails s`. This process will watch for changes in the `app/packs/entrypoints/*.js` files and automatically reload the browser to match. This feature is also known as [Hot Module Replacement](https://webpack.js.org/concepts/hot-module-replacement/).
+If you want to use live code reloading, or you have enough JavaScript that on-demand compilation is too slow, you'll need to run `./bin/webpack-dev-server` or `ruby ./bin/webpack-dev-server`. Windows users will need to run these commands in a terminal separate from `bundle exec rails s`. This process will watch for changes in the relevant files, defined by `webpacker.yml` configuration settings for `source_path`, `source_entry_path`, and `additional_paths`, and it will then automatically reload the browser to match. This feature is also known as [Hot Module Replacement](https://webpack.js.org/concepts/hot-module-replacement/).
```bash
# webpack dev server
./bin/webpack-dev-server
# watcher
-./bin/webpack --watch --colors --progress
+./bin/webpack --watch --progress
# standalone build
-./bin/webpack
+./bin/webpack --progress
+
+# Help
+./bin/webpack help
+
+# Version
+./bin/webpack version
+
+# Info
+./bin/webpack info
```
Once you start this webpack development server, Webpacker will automatically start proxying all webpack asset requests to this server. When you stop this server, Rails will detect that it's not running and Rails will revert back to on-demand compilation _if_ you have the `compile` option set to true in your `config/webpacker.yml`
You can use environment variables as options supported by [webpack-dev-server](https://webpack.js.org/configuration/dev-server/) in the form `WEBPACKER_DEV_SERVER_<OPTION>`. Please note that these environmental variables will always take precedence over the ones already set in the configuration file, and that the _same_ environmental variables must be available to the `rails server` process.