webpacker 6.0.0.pre.2 → 6.0.0.rc.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.github/workflows/jest.yml +5 -2
- data/.github/workflows/js-lint.yml +5 -2
- data/.github/workflows/rubocop.yml +1 -1
- data/.github/workflows/ruby.yml +17 -14
- data/.node-version +1 -1
- data/.rubocop.yml +106 -0
- data/CHANGELOG.md +36 -9
- data/CONTRIBUTING.md +1 -1
- data/Gemfile.lock +93 -90
- data/README.md +363 -107
- data/config/README.md +3 -0
- data/config/webpacker.yml +1 -0
- data/docs/deployment.md +9 -29
- data/docs/developing_webpacker.md +29 -0
- data/docs/troubleshooting.md +57 -25
- data/docs/v6_upgrade.md +75 -0
- data/gemfiles/Gemfile-rails-edge +1 -1
- data/gemfiles/Gemfile-rails.6.1.x +12 -0
- data/lib/install/config/webpacker.yml +5 -7
- data/lib/install/{javascript/packs → packs/entrypoints}/application.js +4 -3
- data/lib/install/template.rb +17 -10
- data/lib/tasks/webpacker/binstubs.rake +2 -2
- data/lib/tasks/webpacker/check_node.rake +3 -0
- data/lib/tasks/webpacker/check_yarn.rake +4 -1
- data/lib/tasks/webpacker/clobber.rake +1 -1
- data/lib/tasks/webpacker/install.rake +2 -2
- data/lib/tasks/webpacker/verify_config.rake +14 -0
- data/lib/tasks/webpacker/verify_install.rake +1 -11
- data/lib/webpacker.rb +1 -1
- data/lib/webpacker/commands.rb +2 -1
- data/lib/webpacker/compiler.rb +9 -3
- data/lib/webpacker/configuration.rb +19 -8
- data/lib/webpacker/dev_server.rb +6 -0
- data/lib/webpacker/dev_server_runner.rb +7 -2
- data/lib/webpacker/env.rb +5 -1
- data/lib/webpacker/helper.rb +26 -50
- data/lib/webpacker/instance.rb +4 -0
- data/lib/webpacker/manifest.rb +1 -2
- data/lib/webpacker/railtie.rb +1 -2
- data/lib/webpacker/runner.rb +1 -1
- data/lib/webpacker/version.rb +1 -1
- data/lib/webpacker/webpack_runner.rb +1 -0
- data/package.json +25 -29
- data/package/__tests__/development.js +3 -2
- data/package/__tests__/env.js +8 -4
- data/package/__tests__/index.js +9 -0
- data/package/babel/preset.js +24 -14
- data/package/env.js +7 -1
- data/package/environments/__tests__/base.js +7 -7
- data/package/environments/base.js +25 -25
- data/package/environments/development.js +7 -8
- data/package/environments/production.js +28 -30
- data/package/index.js +9 -2
- data/package/inliningCss.js +7 -0
- data/package/rules/babel.js +1 -1
- data/package/rules/coffee.js +5 -5
- data/package/rules/erb.js +5 -3
- data/package/rules/file.js +5 -3
- data/package/rules/index.js +9 -17
- data/package/rules/less.js +14 -10
- data/package/rules/raw.js +5 -0
- data/package/rules/sass.js +12 -9
- data/package/rules/stylus.js +26 -0
- data/package/utils/get_style_rule.js +28 -30
- data/package/utils/helpers.js +25 -0
- data/test/configuration_test.rb +3 -3
- data/test/dev_server_runner_test.rb +13 -2
- data/test/helper_test.rb +59 -60
- data/test/manifest_test.rb +16 -0
- data/test/mounted_app/test/dummy/config/webpacker.yml +4 -4
- data/test/test_app/app/{javascript/packs → packs/entrypoints}/application.js +1 -1
- data/test/test_app/app/{javascript/packs → packs/entrypoints}/multi_entry.css +0 -0
- data/test/test_app/app/{javascript/packs → packs/entrypoints}/multi_entry.js +0 -0
- data/test/test_app/config/webpacker.yml +4 -6
- data/test/test_app/config/webpacker_other_location.yml +79 -0
- data/test/test_app/public/packs/manifest.json +19 -5
- data/test/webpacker_test.rb +17 -0
- data/yarn.lock +1567 -1039
- metadata +24 -36
- data/docs/assets.md +0 -135
- data/docs/cloud9.md +0 -310
- data/docs/css.md +0 -303
- data/docs/docker.md +0 -68
- data/docs/engines.md +0 -213
- data/docs/env.md +0 -68
- data/docs/es6.md +0 -72
- data/docs/folder-structure.md +0 -66
- data/docs/integrations.md +0 -220
- data/docs/misc.md +0 -23
- data/docs/props.md +0 -187
- data/docs/react.md +0 -183
- data/docs/target.md +0 -22
- data/docs/testing.md +0 -147
- data/docs/typescript.md +0 -190
- data/docs/v4-upgrade.md +0 -142
- data/docs/webpack-dev-server.md +0 -94
- data/docs/webpack.md +0 -315
- data/docs/yarn.md +0 -23
- data/lib/install/examples/vue3/app.vue +0 -27
- data/lib/install/examples/vue3/hello_vue.js +0 -15
- data/lib/install/javascript/packs/application.css +0 -9
- data/package/babel/preset-react.js +0 -62
- data/package/rules/svg.js +0 -23
data/README.md
CHANGED
@@ -5,11 +5,11 @@
|
|
5
5
|
[![Rubocop](https://github.com/rails/webpacker/workflows/Rubocop/badge.svg)](https://github.com/rails/webpacker/actions)
|
6
6
|
[![JS lint](https://github.com/rails/webpacker/workflows/JS%20lint/badge.svg)](https://github.com/rails/webpacker/actions)
|
7
7
|
|
8
|
-
[![node.js](https://img.shields.io/badge/node-%3E%3D%
|
8
|
+
[![node.js](https://img.shields.io/badge/node-%3E%3D%2012.0.0-brightgreen.svg)](https://www.npmjs.com/package/@rails/webpacker)
|
9
9
|
[![Gem](https://img.shields.io/gem/v/webpacker.svg)](https://rubygems.org/gems/webpacker)
|
10
10
|
|
11
11
|
Webpacker makes it easy to use the JavaScript pre-processor and bundler
|
12
|
-
[
|
12
|
+
[Webpack v5](https://webpack.js.org/)
|
13
13
|
to manage application-like JavaScript in Rails. It coexists with the asset pipeline,
|
14
14
|
as the primary purpose for webpack is app-like JavaScript, not images, CSS, or
|
15
15
|
even JavaScript Sprinkles (that all continues to live in app/assets).
|
@@ -26,27 +26,28 @@ in which case you may not even need the asset pipeline. This is mostly relevant
|
|
26
26
|
|
27
27
|
- [Prerequisites](#prerequisites)
|
28
28
|
- [Features](#features)
|
29
|
+
- [Optional support](#optional-support)
|
29
30
|
- [Installation](#installation)
|
30
31
|
- [Usage](#usage)
|
32
|
+
- [Server-Side Rendering (SSR)](#server-side-rendering-ssr)
|
31
33
|
- [Development](#development)
|
32
34
|
- [Webpack Configuration](#webpack-configuration)
|
35
|
+
- [Integrations](#integrations)
|
36
|
+
- [CoffeeScript](#coffeescript)
|
37
|
+
- [TypeScript](#typescript)
|
38
|
+
- [CSS](#css)
|
39
|
+
- [Postcss](#postcss)
|
40
|
+
- [Sass](#sass)
|
41
|
+
- [Less](#less)
|
42
|
+
- [Stylus](#stylus)
|
43
|
+
- [React](#react)
|
44
|
+
- [Other frameworks](#other-frameworks)
|
33
45
|
- [Custom Rails environments](#custom-rails-environments)
|
34
46
|
- [Upgrading](#upgrading)
|
35
|
-
- [Integrations](#integrations)
|
36
|
-
- [React](./docs/integrations.md#react)
|
37
|
-
- [Angular with TypeScript](./docs/integrations.md#angular-with-typescript)
|
38
|
-
- [Vue](./docs/integrations.md#vue)
|
39
|
-
- [Elm](./docs/integrations.md#elm)
|
40
|
-
- [Stimulus](./docs/integrations.md#stimulus)
|
41
|
-
- [Svelte](./docs/integrations.md#svelte)
|
42
|
-
- [Typescript](./docs/typescript.md)
|
43
|
-
- [CoffeeScript](./docs/integrations.md#coffeescript)
|
44
|
-
- [Erb](./docs/integrations.md#erb)
|
45
47
|
- [Paths](#paths)
|
46
|
-
- [
|
47
|
-
- [Watched](#watched)
|
48
|
+
- [Additional paths](#additional-paths)
|
48
49
|
- [Deployment](#deployment)
|
49
|
-
- [
|
50
|
+
- [Troubleshooting](#troubleshooting)
|
50
51
|
- [Contributing](#contributing)
|
51
52
|
- [License](#license)
|
52
53
|
|
@@ -56,23 +57,28 @@ in which case you may not even need the asset pipeline. This is mostly relevant
|
|
56
57
|
|
57
58
|
- Ruby 2.4+
|
58
59
|
- Rails 5.2+
|
59
|
-
- Node.js
|
60
|
-
- Yarn 1.x+
|
60
|
+
- Node.js 12+ || 14+
|
61
|
+
- Yarn 1.x+ || 2.x+
|
61
62
|
|
62
63
|
## Features
|
63
64
|
|
64
|
-
- [
|
65
|
+
- [Webpack v5](https://webpack.js.org/)
|
65
66
|
- ES6 with [babel](https://babeljs.io/)
|
66
67
|
- Automatic code splitting using multiple entry points
|
67
|
-
- Stylesheets - Sass and CSS
|
68
|
-
- Images and fonts
|
69
|
-
- PostCSS - Auto-Prefixer
|
70
68
|
- Asset compression, source-maps, and minification
|
71
69
|
- CDN support
|
72
|
-
- React, Angular, Elm and Vue support out-of-the-box
|
73
70
|
- Rails view helpers
|
74
71
|
- Extensible and configurable
|
75
72
|
|
73
|
+
### Optional support
|
74
|
+
|
75
|
+
_requires extra packages to be installed_
|
76
|
+
|
77
|
+
- Stylesheets - Sass, Less, Stylus and Css, PostCSS
|
78
|
+
- CoffeeScript
|
79
|
+
- TypeScript
|
80
|
+
- React
|
81
|
+
|
76
82
|
## Installation
|
77
83
|
|
78
84
|
You can either add Webpacker during setup of a new Rails 5.1+ application
|
@@ -87,12 +93,11 @@ Or add it to your `Gemfile`:
|
|
87
93
|
|
88
94
|
```ruby
|
89
95
|
# Gemfile
|
90
|
-
gem 'webpacker', '~>
|
96
|
+
gem 'webpacker', '~> 6.x'
|
91
97
|
|
92
98
|
# OR if you prefer to use master
|
93
99
|
gem 'webpacker', git: 'https://github.com/rails/webpacker.git'
|
94
100
|
yarn add https://github.com/rails/webpacker.git
|
95
|
-
yarn add core-js regenerator-runtime
|
96
101
|
```
|
97
102
|
|
98
103
|
Finally, run the following to install Webpacker:
|
@@ -122,9 +127,9 @@ yarn install
|
|
122
127
|
Once installed, you can start writing modern ES6-flavored JavaScript apps right away:
|
123
128
|
|
124
129
|
```yml
|
125
|
-
app/
|
126
|
-
├──
|
127
|
-
│ #
|
130
|
+
app/packs:
|
131
|
+
├── entrypoints:
|
132
|
+
│ # Only Webpack entry files here
|
128
133
|
│ └── application.js
|
129
134
|
│ └── application.css
|
130
135
|
└── src:
|
@@ -135,34 +140,20 @@ app/javascript:
|
|
135
140
|
└── logo.svg
|
136
141
|
```
|
137
142
|
|
138
|
-
|
139
|
-
|
140
|
-
```js
|
141
|
-
import 'core-js/stable'
|
142
|
-
import 'regenerator-runtime/runtime'
|
143
|
-
```
|
144
|
-
|
145
|
-
You can then link the JavaScript pack in Rails views using the `javascript_pack_tag` helper.
|
146
|
-
If you have styles imported in your pack file, you can link them by using `stylesheet_pack_tag`:
|
143
|
+
You can then link the JavaScript pack in Rails views using the `javascript_pack_tag` helper. If you have styles imported in your pack file, you can link them by using `stylesheet_pack_tag`:
|
147
144
|
|
148
145
|
```erb
|
149
146
|
<%= javascript_pack_tag 'application' %>
|
150
147
|
<%= stylesheet_pack_tag 'application' %>
|
151
148
|
```
|
152
149
|
|
153
|
-
|
154
|
-
|
155
|
-
|
156
|
-
```erb
|
157
|
-
<link rel="prefetch" href="<%= asset_pack_path 'application.css' %>" />
|
158
|
-
<img src="<%= asset_pack_path 'images/logo.svg' %>" />
|
159
|
-
```
|
150
|
+
The `javascript_pack_tag` and `stylesheet_pack_tag` helpers will include all the transpiled
|
151
|
+
packs with the chunks in your view, which creates html tags for all the chunks.
|
160
152
|
|
161
|
-
|
162
|
-
tags for a pack and all the dependent chunks.
|
153
|
+
The result looks like this:
|
163
154
|
|
164
155
|
```erb
|
165
|
-
<%=
|
156
|
+
<%= javascript_pack_tag 'calendar', 'map' %>
|
166
157
|
|
167
158
|
<script src="/packs/vendor-16838bab065ae1e314.js" data-turbolinks-track="reload"></script>
|
168
159
|
<script src="/packs/calendar~runtime-16838bab065ae1e314.js" data-turbolinks-track="reload"></script>
|
@@ -171,20 +162,59 @@ tags for a pack and all the dependent chunks.
|
|
171
162
|
<script src="/packs/map-16838bab065ae1e314.js" data-turbolinks-track="reload"></script>
|
172
163
|
```
|
173
164
|
|
174
|
-
**Important:** Pass all your pack names when using
|
175
|
-
|
165
|
+
**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
|
166
|
+
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.
|
176
167
|
|
177
168
|
```erb
|
178
169
|
<%# DO %>
|
179
|
-
<%=
|
170
|
+
<%= javascript_pack_tag 'calendar', 'map' %>
|
171
|
+
<%= stylesheet_pack_tag 'calendar', 'map' %>
|
180
172
|
|
181
173
|
<%# DON'T %>
|
182
|
-
<%=
|
183
|
-
<%=
|
174
|
+
<%= javascript_pack_tag 'calendar' %>
|
175
|
+
<%= javascript_pack_tag 'map' %>
|
176
|
+
<%= stylesheet_pack_tag 'calendar' %>
|
177
|
+
<%= stylesheet_pack_tag 'map' %>
|
178
|
+
```
|
179
|
+
|
180
|
+
If you want to link a static asset for `<img />` tag, you can use the `asset_pack_path` helper:
|
181
|
+
```erb
|
182
|
+
<img src="<%= asset_pack_path 'images/logo.svg' %>" />
|
184
183
|
```
|
185
184
|
|
185
|
+
Or use the dedicated helper:
|
186
|
+
```erb
|
187
|
+
<%= image_pack_tag 'application.png', size: '16x10', alt: 'Edit Entry' %>
|
188
|
+
<%= image_pack_tag 'picture.png', srcset: { 'picture-2x.png' => '2x' } %>
|
189
|
+
```
|
190
|
+
|
191
|
+
If you want to create a favicon:
|
192
|
+
```erb
|
193
|
+
<%= favicon_pack_tag 'mb-icon.png', rel: 'apple-touch-icon', type: 'image/png' %>
|
194
|
+
```
|
195
|
+
|
196
|
+
If you want to preload a static asset in your `<head>`, you can use the `preload_pack_asset` helper:
|
197
|
+
```erb
|
198
|
+
<%= preload_pack_asset 'fonts/fa-regular-400.woff2' %>
|
199
|
+
```
|
200
|
+
|
201
|
+
If you want to use images in your stylesheets:
|
202
|
+
|
203
|
+
```css
|
204
|
+
.foo {
|
205
|
+
background-image: url('../images/logo.svg')
|
206
|
+
}
|
207
|
+
```
|
208
|
+
|
209
|
+
#### Server-Side Rendering (SSR)
|
210
|
+
Note, if you are using server-side rendering of JavaScript with dynamic code-spliting,
|
211
|
+
as is often done with extensions to Webpacker, like [React on Rails](https://github.com/shakacode/react_on_rails)
|
212
|
+
your JavaScript should create the link prefetch HTML tags that you will use, so you won't
|
213
|
+
need to use to `asset_pack_path` in those circumstances.
|
214
|
+
|
186
215
|
**Note:** In order for your styles or static assets files to be available in your view,
|
187
|
-
you would need to link them in your "pack" or entry file.
|
216
|
+
you would need to link them in your "pack" or entry file. Otherwise, Webpack won't know
|
217
|
+
to package up those files.
|
188
218
|
|
189
219
|
### Development
|
190
220
|
|
@@ -196,11 +226,20 @@ are loaded based on your environment.
|
|
196
226
|
In development, Webpacker compiles on demand rather than upfront by default. This
|
197
227
|
happens when you refer to any of the pack assets using the Webpacker helper methods.
|
198
228
|
This means that you don't have to run any separate processes. Compilation errors are logged
|
199
|
-
to the standard Rails log.
|
229
|
+
to the standard Rails log. However, this auto-compilation happens when a web request
|
230
|
+
is made that requires an updated webpack build, not when files change. Thus, that can
|
231
|
+
be painfully slow for front-end development in this default way. Instead, you should either
|
232
|
+
run the `bin/webpack --watch` or run `./bin/webpack-dev-server`
|
200
233
|
|
201
|
-
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`.
|
202
|
-
in a terminal separate from `bundle exec rails s`.
|
203
|
-
in the `app/
|
234
|
+
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`.
|
235
|
+
Windows users will need to run these commands in a terminal separate from `bundle exec rails s`.
|
236
|
+
This process will watch for changes in the `app/packs/entrypoints/*.js` files and automatically
|
237
|
+
reload the browser to match. This feature is also known as
|
238
|
+
[Hot Module Replacement](https://webpack.js.org/concepts/hot-module-replacement/).
|
239
|
+
|
240
|
+
HMR is only the first step to running "Fast Refresh" with React. For more information
|
241
|
+
on how to configure rails/webpacker for Fast Refresh with React, see article
|
242
|
+
[HMR and React Hot Reloading](https://github.com/shakacode/react_on_rails/blob/master/docs/rails-webpacker-react-integration-options.md#hmr-and-react-hot-reloading).
|
204
243
|
|
205
244
|
```bash
|
206
245
|
# webpack dev server
|
@@ -213,9 +252,10 @@ in the `app/javascript/packs/*.js` files and automatically reload the browser to
|
|
213
252
|
./bin/webpack
|
214
253
|
```
|
215
254
|
|
216
|
-
Once you start this development server, Webpacker will automatically start proxying all
|
217
|
-
webpack asset requests to this server. When you stop
|
218
|
-
on-demand compilation
|
255
|
+
Once you start this webpack development server, Webpacker will automatically start proxying all
|
256
|
+
webpack asset requests to this server. When you stop this server, Rails will detect
|
257
|
+
that it's not running and Rails will revert back to on-demand compilation _if_ you have
|
258
|
+
the `compile` option set to true in your `config/webpacker.yml`
|
219
259
|
|
220
260
|
You can use environment variables as options supported by
|
221
261
|
[webpack-dev-server](https://webpack.js.org/configuration/dev-server/) in the
|
@@ -248,7 +288,241 @@ WEBPACKER_DEV_SERVER_HOST=0.0.0.0 ./bin/webpack-dev-server
|
|
248
288
|
|
249
289
|
### Webpack Configuration
|
250
290
|
|
251
|
-
|
291
|
+
Webpacker gives you a default set of configuration files for test, development and
|
292
|
+
production environments in `config/webpack/*.js`. You can configure each individual
|
293
|
+
environment in their respective files or configure them all in the base
|
294
|
+
`config/webpack/base.js` file.
|
295
|
+
|
296
|
+
By default, you don't need to make any changes to `config/webpack/*.js`
|
297
|
+
files since it's all standard production-ready configuration. However,
|
298
|
+
if you do need to customize or add a new loader, this is where you would go.
|
299
|
+
|
300
|
+
Here is how you can modify webpack configuration:
|
301
|
+
|
302
|
+
You might add separate files to keep your code more organized.
|
303
|
+
|
304
|
+
```js
|
305
|
+
// config/webpack/custom.js
|
306
|
+
module.exports = {
|
307
|
+
resolve: {
|
308
|
+
alias: {
|
309
|
+
jquery: 'jquery/src/jquery',
|
310
|
+
vue: 'vue/dist/vue.js',
|
311
|
+
React: 'react',
|
312
|
+
ReactDOM: 'react-dom',
|
313
|
+
vue_resource: 'vue-resource/dist/vue-resource'
|
314
|
+
}
|
315
|
+
}
|
316
|
+
}
|
317
|
+
```
|
318
|
+
|
319
|
+
Then `require` this file in your `config/webpack/base.js`:
|
320
|
+
|
321
|
+
```js
|
322
|
+
// config/webpack/base.js
|
323
|
+
const { webpackConfig, merge } = require('@rails/webpacker')
|
324
|
+
const customConfig = require('./custom')
|
325
|
+
|
326
|
+
module.exports = merge(webpackConfig, customConfig)
|
327
|
+
```
|
328
|
+
|
329
|
+
If you need access to configs within Webpacker's configuration,
|
330
|
+
you can import them like so:
|
331
|
+
|
332
|
+
```js
|
333
|
+
// config/webpack/base.js
|
334
|
+
const { webpackConfig } = require('@rails/webpacker')
|
335
|
+
|
336
|
+
console.log(webpackConfig.output_path)
|
337
|
+
console.log(webpackConfig.source_path)
|
338
|
+
|
339
|
+
// Or to print out your whole webpack configuration
|
340
|
+
console.log(JSON.stringify(webpackConfig, undefined, 2))
|
341
|
+
```
|
342
|
+
|
343
|
+
### Integrations
|
344
|
+
|
345
|
+
Webpacker out of the box supports JS and static assets (fonts, images etc.)
|
346
|
+
compilation. To enable support for CoffeeScript or TypeScript install
|
347
|
+
relevant packages:
|
348
|
+
|
349
|
+
#### CoffeeScript
|
350
|
+
|
351
|
+
```bash
|
352
|
+
yarn add coffeescript coffee-loader
|
353
|
+
```
|
354
|
+
|
355
|
+
#### TypeScript
|
356
|
+
|
357
|
+
```bash
|
358
|
+
yarn add typescript @babel/preset-typescript
|
359
|
+
```
|
360
|
+
|
361
|
+
Add tsconfig.json
|
362
|
+
|
363
|
+
```json
|
364
|
+
{
|
365
|
+
"compilerOptions": {
|
366
|
+
"declaration": false,
|
367
|
+
"emitDecoratorMetadata": true,
|
368
|
+
"experimentalDecorators": true,
|
369
|
+
"lib": ["es6", "dom"],
|
370
|
+
"module": "es6",
|
371
|
+
"moduleResolution": "node",
|
372
|
+
"baseUrl": ".",
|
373
|
+
"paths": {
|
374
|
+
"*": ["node_modules/*", "app/packs/*"]
|
375
|
+
},
|
376
|
+
"sourceMap": true,
|
377
|
+
"target": "es5",
|
378
|
+
"noEmit": true
|
379
|
+
},
|
380
|
+
"exclude": ["**/*.spec.ts", "node_modules", "vendor", "public"],
|
381
|
+
"compileOnSave": false
|
382
|
+
}
|
383
|
+
```
|
384
|
+
|
385
|
+
Babel won’t perform any type-checking on TypeScript code. To optionally use type-checking run:
|
386
|
+
|
387
|
+
```bash
|
388
|
+
yarn add fork-ts-checker-webpack-plugin
|
389
|
+
```
|
390
|
+
|
391
|
+
Then modify the webpack config to use it as a plugin:
|
392
|
+
|
393
|
+
```js
|
394
|
+
// config/webpack/base.js
|
395
|
+
const { webpackConfig, merge } = require("@rails/webpacker");
|
396
|
+
const ForkTSCheckerWebpackPlugin = require("fork-ts-checker-webpack-plugin");
|
397
|
+
|
398
|
+
module.exports = merge(webpackConfig, {
|
399
|
+
plugins: [new ForkTSCheckerWebpackPlugin()],
|
400
|
+
});
|
401
|
+
```
|
402
|
+
|
403
|
+
#### CSS
|
404
|
+
|
405
|
+
To enable CSS support in your application, add following packages:
|
406
|
+
|
407
|
+
```bash
|
408
|
+
yarn add css-loader style-loader mini-css-extract-plugin css-minimizer-webpack-plugin
|
409
|
+
```
|
410
|
+
|
411
|
+
Optionally, add the `CSS` extension to webpack config for easy resolution.
|
412
|
+
|
413
|
+
```js
|
414
|
+
// config/webpack/base.js
|
415
|
+
const { webpackConfig, merge } = require('@rails/webpacker')
|
416
|
+
const customConfig = {
|
417
|
+
resolve: {
|
418
|
+
extensions: ['.css']
|
419
|
+
}
|
420
|
+
}
|
421
|
+
|
422
|
+
module.exports = merge(webpackConfig, customConfig)
|
423
|
+
```
|
424
|
+
|
425
|
+
To enable `PostCSS`, `Sass` or `Less` support, add `CSS` support first and
|
426
|
+
then add the relevant pre-processors:
|
427
|
+
|
428
|
+
#### Postcss
|
429
|
+
|
430
|
+
```bash
|
431
|
+
yarn add postcss postcss-loader
|
432
|
+
```
|
433
|
+
|
434
|
+
Optionally add these two plugins if they are required in your `postcss.config.js`:
|
435
|
+
```bash
|
436
|
+
yarn add postcss-preset-env postcss-flexbugs-fixes
|
437
|
+
```
|
438
|
+
|
439
|
+
#### Sass
|
440
|
+
|
441
|
+
```bash
|
442
|
+
yarn add sass sass-loader
|
443
|
+
```
|
444
|
+
|
445
|
+
#### Less
|
446
|
+
|
447
|
+
```bash
|
448
|
+
yarn add less less-loader
|
449
|
+
```
|
450
|
+
|
451
|
+
#### Stylus
|
452
|
+
|
453
|
+
```bash
|
454
|
+
yarn add stylus stylus-loader
|
455
|
+
```
|
456
|
+
|
457
|
+
#### React
|
458
|
+
|
459
|
+
React is supported and you just need to add relevant packages,
|
460
|
+
|
461
|
+
```bash
|
462
|
+
yarn add react react-dom @babel/preset-react
|
463
|
+
```
|
464
|
+
|
465
|
+
if you are using typescript, update your `tsconfig.json`
|
466
|
+
|
467
|
+
```json
|
468
|
+
{
|
469
|
+
"compilerOptions": {
|
470
|
+
"declaration": false,
|
471
|
+
"emitDecoratorMetadata": true,
|
472
|
+
"experimentalDecorators": true,
|
473
|
+
"lib": ["es6", "dom"],
|
474
|
+
"module": "es6",
|
475
|
+
"moduleResolution": "node",
|
476
|
+
"sourceMap": true,
|
477
|
+
"target": "es5",
|
478
|
+
"jsx": "react",
|
479
|
+
"noEmit": true
|
480
|
+
},
|
481
|
+
"exclude": ["**/*.spec.ts", "node_modules", "vendor", "public"],
|
482
|
+
"compileOnSave": false
|
483
|
+
}
|
484
|
+
```
|
485
|
+
|
486
|
+
For more information on React props hydration and Server-Side Rendering (SSR), see the article
|
487
|
+
[Rails/Webpacker React Integration Options](https://github.com/shakacode/react_on_rails/blob/master/docs/rails-webpacker-react-integration-options.md)
|
488
|
+
in the [ShakaCode/react_on_rails](https://github.com/shakacode/react_on_rails) repo.
|
489
|
+
|
490
|
+
#### Other frameworks
|
491
|
+
|
492
|
+
Please follow webpack integration guide for relevant framework or library,
|
493
|
+
|
494
|
+
1. [Svelte](https://github.com/sveltejs/svelte-loader#install)
|
495
|
+
2. [Angular](https://v2.angular.io/docs/ts/latest/guide/webpack.html#!#configure-webpack)
|
496
|
+
3. [Vue](https://vue-loader.vuejs.org/guide/)
|
497
|
+
|
498
|
+
For example to add Vue support:
|
499
|
+
```js
|
500
|
+
// config/webpack/rules/vue.js
|
501
|
+
const { VueLoaderPlugin } = require('vue-loader')
|
502
|
+
|
503
|
+
module.exports = {
|
504
|
+
module: {
|
505
|
+
rules: [
|
506
|
+
{
|
507
|
+
test: /\.vue$/,
|
508
|
+
loader: 'vue-loader'
|
509
|
+
}
|
510
|
+
]
|
511
|
+
},
|
512
|
+
plugins: [new VueLoaderPlugin()],
|
513
|
+
resolve: {
|
514
|
+
extensions: ['.vue']
|
515
|
+
}
|
516
|
+
}
|
517
|
+
```
|
518
|
+
|
519
|
+
```js
|
520
|
+
// config/webpack/base.js
|
521
|
+
const { webpackConfig, merge } = require('@rails/webpacker')
|
522
|
+
const vueConfig = require('./rules/vue')
|
523
|
+
|
524
|
+
module.exports = merge(vueConfig, webpackConfig)
|
525
|
+
```
|
252
526
|
|
253
527
|
### Custom Rails environments
|
254
528
|
|
@@ -290,11 +564,11 @@ Please note, binstubs compiles in development mode however rake tasks
|
|
290
564
|
compiles in production mode.
|
291
565
|
|
292
566
|
```bash
|
293
|
-
# Compiles in development mode unless NODE_ENV is specified
|
567
|
+
# Compiles in development mode unless NODE_ENV is specified, per the binstub source
|
294
568
|
./bin/webpack
|
295
569
|
./bin/webpack-dev-server
|
296
570
|
|
297
|
-
#
|
571
|
+
# Compiles in production mode by default unless NODE_ENV is specified, per `lib/tasks/webpacker/compile.rake`
|
298
572
|
bundle exec rails assets:precompile
|
299
573
|
bundle exec rails webpacker:compile
|
300
574
|
```
|
@@ -304,32 +578,25 @@ bundle exec rails webpacker:compile
|
|
304
578
|
You can run following commands to upgrade Webpacker to the latest stable version. This process involves upgrading the gem and related JavaScript packages:
|
305
579
|
|
306
580
|
```bash
|
581
|
+
# check your Gemfile for version restrictions
|
307
582
|
bundle update webpacker
|
583
|
+
|
584
|
+
# overwrite your changes to the default install files and revert any unwanted changes from the install
|
308
585
|
rails webpacker:install
|
586
|
+
|
587
|
+
# yarn 1 instructions
|
309
588
|
yarn upgrade @rails/webpacker --latest
|
310
589
|
yarn upgrade webpack-dev-server --latest
|
311
590
|
|
591
|
+
# yarn 2 instructions
|
592
|
+
yarn up @rails/webpacker@latest
|
593
|
+
yarn up webpack-dev-server@latest
|
594
|
+
|
312
595
|
# Or to install the latest release (including pre-releases)
|
313
596
|
yarn add @rails/webpacker@next
|
314
597
|
```
|
315
598
|
|
316
|
-
|
317
|
-
|
318
|
-
Webpacker ships with basic out-of-the-box integration. You can see a list of available commands/tasks by running `bundle exec rails webpacker`.
|
319
|
-
|
320
|
-
Included install integrations:
|
321
|
-
|
322
|
-
- [React](./docs/integrations.md#React)
|
323
|
-
- [Angular with TypeScript](./docs/integrations.md#Angular-with-TypeScript)
|
324
|
-
- [Vue](./docs/integrations.md#Vue)
|
325
|
-
- [Elm](./docs/integrations.md#Elm)
|
326
|
-
- [Svelte](./docs/integrations.md#Svelte)
|
327
|
-
- [Stimulus](./docs/integrations.md#Stimulus)
|
328
|
-
- [CoffeeScript](./docs/integrations.md#CoffeeScript)
|
329
|
-
- [Typescript](./docs/typescript.md)
|
330
|
-
- [Erb](./docs/integrations.md#Erb)
|
331
|
-
|
332
|
-
See [Integrations](./docs/integrations.md) for further details.
|
599
|
+
Also, consult the [CHANGELOG](./CHANGELOG.md) for additional upgrade links.
|
333
600
|
|
334
601
|
## Paths
|
335
602
|
|
@@ -338,19 +605,18 @@ app files and compiled webpack bundles will go in your Rails app.
|
|
338
605
|
All these options are configurable from `config/webpacker.yml` file.
|
339
606
|
|
340
607
|
The configuration for what webpack is supposed to compile by default rests
|
341
|
-
on the convention that every file in `app/
|
608
|
+
on the convention that every file in `app/packs/entrypoints/*`**(default)**
|
342
609
|
or whatever path you set for `source_entry_path` in the `webpacker.yml` configuration
|
343
610
|
is turned into their own output files (or entry points, as webpack calls it). Therefore you don't want to put anything inside `packs` directory that you do not want to be
|
344
611
|
an entry file. As a rule of thumb, put all files you want to link in your views inside
|
345
|
-
"packs" directory and keep everything else under `app/
|
612
|
+
"packs" directory and keep everything else under `app/packs`.
|
346
613
|
|
347
|
-
Suppose you want to change the source directory from `app/
|
614
|
+
Suppose you want to change the source directory from `app/packs`
|
348
615
|
to `frontend` and output to `assets/packs`. This is how you would do it:
|
349
616
|
|
350
617
|
```yml
|
351
618
|
# config/webpacker.yml
|
352
|
-
source_path: frontend
|
353
|
-
source_entry_path: packs
|
619
|
+
source_path: frontend # packs are in frontend/packs
|
354
620
|
public_output_path: assets/packs # outputs to => public/assets/packs
|
355
621
|
```
|
356
622
|
|
@@ -364,18 +630,20 @@ development:
|
|
364
630
|
port: 3035
|
365
631
|
```
|
366
632
|
|
367
|
-
If you have `hmr` turned to true, then the `stylesheet_pack_tag` generates no output,
|
633
|
+
If you have `hmr` turned to true, then the `stylesheet_pack_tag` generates no output,
|
634
|
+
as you will want to configure your styles to be inlined in your JavaScript for hot reloading.
|
635
|
+
During production and testing, the `stylesheet_pack_tag` will create the appropriate HTML tags.
|
368
636
|
|
369
|
-
###
|
637
|
+
### Additional paths
|
370
638
|
|
371
639
|
If you are adding Webpacker to an existing app that has most of the assets inside
|
372
640
|
`app/assets` or inside an engine, and you want to share that
|
373
641
|
with webpack modules, you can use the `additional_paths`
|
374
642
|
option available in `config/webpacker.yml`. This lets you
|
375
|
-
add additional paths that webpack should
|
643
|
+
add additional paths that webpack should look up when resolving modules:
|
376
644
|
|
377
645
|
```yml
|
378
|
-
additional_paths: ['app/assets']
|
646
|
+
additional_paths: ['app/assets', 'vendor/assets']
|
379
647
|
```
|
380
648
|
|
381
649
|
You can then import these items inside your modules like so:
|
@@ -390,31 +658,19 @@ import 'images/rails.png'
|
|
390
658
|
will make the compilation slow, consider adding specific paths instead of
|
391
659
|
whole parent directory if you just need to reference one or two modules
|
392
660
|
|
661
|
+
**Also note:** While importing assets living outside your `source_path` defined in webpacker.yml (like, for instance, assets under `app/assets`) from within your packs using _relative_ paths like `import '../../assets/javascripts/file.js'` will work in development, Webpacker won't recompile the bundle in production unless a file that lives in one of it's watched paths has changed (check out `Webpacker::Compiler#watched_files_digest`). That's why you'd need to add `app/assets` to the additional_paths as stated above and use `import 'javascripts/file.js'` instead.
|
662
|
+
|
393
663
|
## Deployment
|
394
664
|
|
395
665
|
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, `webpacker:compile` is automatically aliased to `assets:precompile`. Similar to sprockets both rake tasks will compile packs in production mode but will use `RAILS_ENV` to load configuration from `config/webpacker.yml` (if available).
|
396
666
|
|
397
667
|
When compiling assets for production on a remote server, such as a continuous integration environment, it's recommended to use `yarn install --frozen-lockfile` to install NPM packages on the remote host to ensure that the installed packages match the `yarn.lock` file.
|
398
668
|
|
399
|
-
|
400
|
-
|
401
|
-
|
402
|
-
|
403
|
-
|
404
|
-
- [Environment Variables](./docs/env.md)
|
405
|
-
- [Folder Structure](./docs/folder-structure.md)
|
406
|
-
- [Assets](./docs/assets.md) - [CSS, Sass and SCSS](./docs/css.md) - [ES6](./docs/es6.md), [Target browsers](./docs/target.md)
|
407
|
-
- [Props](./docs/props.md)
|
408
|
-
- [Typescript](./docs/typescript.md)
|
409
|
-
- [Yarn](./docs/yarn.md)
|
410
|
-
- [Misc](./docs/misc.md)
|
411
|
-
- [Deployment](./docs/deployment.md)
|
412
|
-
- [Docker](./docs/docker.md)
|
413
|
-
- [Using in Rails engines](./docs/engines.md)
|
414
|
-
- [Webpacker on Cloud9](./docs/cloud9.md)
|
415
|
-
- [Testing](./docs/testing.md)
|
416
|
-
- [Troubleshooting](./docs/troubleshooting.md)
|
417
|
-
- [v3 to v4 Upgrade Guide](./docs/v4-upgrade.md)
|
669
|
+
If you are using a CDN setup, webpacker will use the configured [asset host](https://guides.rubyonrails.org/configuring.html#rails-general-configuration) value to prefix URLs for images or font icons which are included inside JS code or CSS. It is possible to override this value during asset compilation by setting the `WEBPACKER_ASSET_HOST` environment variable.
|
670
|
+
|
671
|
+
## Troubleshooting
|
672
|
+
|
673
|
+
See the doc page for [Troubleshooting](./docs/troubleshooting.md).
|
418
674
|
|
419
675
|
## Contributing
|
420
676
|
|