webpacker 4.0.7 → 5.4.4
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.eslintrc.js +8 -8
- data/.github/workflows/jest.yml +38 -0
- data/.github/workflows/js-lint.yml +39 -0
- data/.github/workflows/rubocop.yml +39 -0
- data/.github/workflows/ruby.yml +46 -0
- data/.node-version +1 -1
- data/.rubocop.yml +118 -14
- data/CHANGELOG.md +301 -138
- data/CONTRIBUTING.md +1 -1
- data/Gemfile +1 -0
- data/Gemfile.lock +123 -92
- data/README.md +86 -211
- data/docs/css.md +72 -6
- data/docs/deployment.md +40 -11
- data/docs/docker.md +33 -14
- data/docs/engines.md +53 -3
- data/docs/env.md +0 -2
- data/docs/es6.md +19 -1
- data/docs/integrations.md +220 -0
- data/docs/target.md +22 -0
- data/docs/testing.md +2 -3
- data/docs/troubleshooting.md +39 -9
- data/docs/typescript.md +93 -26
- data/docs/webpack-dev-server.md +2 -2
- data/docs/webpack.md +18 -3
- data/gemfiles/Gemfile-rails-edge +1 -1
- data/gemfiles/{Gemfile-rails.4.2.x → Gemfile-rails.6.0.x} +1 -1
- data/lib/install/bin/webpack +0 -1
- data/lib/install/bin/webpack-dev-server +0 -1
- data/lib/install/coffee.rb +1 -1
- data/lib/install/config/babel.config.js +23 -13
- data/lib/install/config/webpacker.yml +3 -6
- data/lib/install/elm.rb +1 -1
- data/lib/install/erb.rb +2 -2
- data/lib/install/examples/angular/hello_angular/polyfills.ts +2 -2
- data/lib/install/examples/react/babel.config.js +28 -14
- data/lib/install/examples/react/tsconfig.json +2 -1
- data/lib/install/examples/svelte/app.svelte +11 -0
- data/lib/install/examples/svelte/hello_svelte.js +20 -0
- data/lib/install/examples/typescript/tsconfig.json +2 -1
- data/lib/install/loaders/elm.js +9 -6
- data/lib/install/loaders/svelte.js +9 -0
- data/lib/install/svelte.rb +29 -0
- data/lib/install/template.rb +14 -6
- data/lib/install/typescript.rb +6 -13
- data/lib/install/vue.rb +1 -1
- data/lib/tasks/installers.rake +1 -0
- data/lib/tasks/webpacker/check_node.rake +15 -8
- data/lib/tasks/webpacker/check_yarn.rake +16 -10
- data/lib/tasks/webpacker/clean.rake +25 -0
- data/lib/tasks/webpacker/clobber.rake +8 -4
- data/lib/tasks/webpacker/compile.rake +2 -10
- data/lib/tasks/webpacker/yarn_install.rake +11 -1
- data/lib/tasks/webpacker.rake +2 -0
- data/lib/webpacker/commands.rb +53 -1
- data/lib/webpacker/compiler.rb +21 -10
- data/lib/webpacker/configuration.rb +36 -13
- data/lib/webpacker/dev_server.rb +1 -1
- data/lib/webpacker/dev_server_proxy.rb +5 -9
- data/lib/webpacker/dev_server_runner.rb +6 -6
- data/lib/webpacker/env.rb +6 -2
- data/lib/webpacker/helper.rb +70 -25
- data/lib/webpacker/manifest.rb +4 -4
- data/lib/webpacker/railtie.rb +6 -43
- data/lib/webpacker/runner.rb +1 -0
- data/lib/webpacker/version.rb +1 -1
- data/lib/webpacker/webpack_runner.rb +2 -2
- data/lib/webpacker.rb +9 -1
- data/package/__tests__/config.js +12 -24
- data/package/__tests__/dev_server.js +2 -0
- data/package/__tests__/development.js +14 -1
- data/package/config.js +6 -11
- data/package/configPath.js +3 -0
- data/package/config_types/config_list.js +3 -3
- data/package/config_types/config_object.js +1 -1
- data/package/dev_server.js +1 -1
- data/package/env.js +1 -2
- data/package/environments/__tests__/base.js +29 -2
- data/package/environments/base.js +18 -8
- data/package/environments/development.js +39 -37
- data/package/environments/production.js +12 -2
- data/package/rules/babel.js +12 -5
- data/package/rules/file.js +3 -2
- data/package/rules/node_modules.js +3 -5
- data/package/rules/sass.js +11 -2
- data/package/utils/__tests__/get_style_rule.js +9 -0
- data/package/utils/deep_merge.js +5 -5
- data/package/utils/get_style_rule.js +7 -12
- data/package/utils/helpers.js +10 -10
- data/package.json +43 -43
- data/test/command_test.rb +6 -0
- data/test/compiler_test.rb +10 -6
- data/test/configuration_test.rb +40 -30
- data/test/dev_server_runner_test.rb +1 -1
- data/test/dev_server_test.rb +22 -0
- data/test/helper_test.rb +58 -9
- data/test/manifest_test.rb +37 -6
- data/test/rake_tasks_test.rb +17 -0
- data/test/test_app/app/javascript/packs/multi_entry.css +4 -0
- data/test/test_app/app/javascript/packs/multi_entry.js +4 -0
- data/test/test_app/bin/webpack +0 -1
- data/test/test_app/bin/webpack-dev-server +0 -1
- data/test/test_app/config/application.rb +0 -1
- data/test/test_app/config/webpacker.yml +8 -1
- data/test/test_app/public/packs/manifest.json +4 -0
- data/test/webpack_runner_test.rb +1 -1
- data/webpacker.gemspec +6 -4
- data/yarn.lock +4350 -4099
- metadata +63 -23
- data/.travis.yml +0 -53
- data/gemfiles/Gemfile-rails.5.0.x +0 -9
- data/gemfiles/Gemfile-rails.5.1.x +0 -9
- data/lib/install/loaders/typescript.js +0 -11
data/README.md
CHANGED
@@ -1,8 +1,12 @@
|
|
1
1
|
# Webpacker
|
2
2
|
|
3
|
-
[![
|
4
|
-
[![
|
5
|
-
[![
|
3
|
+
[![Ruby specs](https://github.com/rails/webpacker/workflows/Ruby%20specs/badge.svg)](https://github.com/rails/webpacker/actions)
|
4
|
+
[![Jest specs](https://github.com/rails/webpacker/workflows/Jest%20specs/badge.svg)](https://github.com/rails/webpacker/actions)
|
5
|
+
[![Rubocop](https://github.com/rails/webpacker/workflows/Rubocop/badge.svg)](https://github.com/rails/webpacker/actions)
|
6
|
+
[![JS lint](https://github.com/rails/webpacker/workflows/JS%20lint/badge.svg)](https://github.com/rails/webpacker/actions)
|
7
|
+
|
8
|
+
[![node.js](https://img.shields.io/badge/node-%3E%3D%2010.17.0-brightgreen.svg)](https://www.npmjs.com/package/@rails/webpacker)
|
9
|
+
[![Gem](https://img.shields.io/gem/v/webpacker.svg)](https://rubygems.org/gems/webpacker)
|
6
10
|
|
7
11
|
Webpacker makes it easy to use the JavaScript pre-processor and bundler
|
8
12
|
[webpack 4.x.x+](https://webpack.js.org/)
|
@@ -13,10 +17,11 @@ even JavaScript Sprinkles (that all continues to live in app/assets).
|
|
13
17
|
However, it is possible to use Webpacker for CSS, images and fonts assets as well,
|
14
18
|
in which case you may not even need the asset pipeline. This is mostly relevant when exclusively using component-based JavaScript frameworks.
|
15
19
|
|
16
|
-
**NOTE:** The master branch now hosts the code for
|
20
|
+
**NOTE:** The master branch now hosts the code for v5.x.x. Please refer to [4-x-stable](https://github.com/rails/webpacker/tree/4-x-stable) branch for 4.x documentation.
|
17
21
|
|
18
22
|
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
19
23
|
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
24
|
+
|
20
25
|
## Table of Contents
|
21
26
|
|
22
27
|
- [Prerequisites](#prerequisites)
|
@@ -27,15 +32,16 @@ in which case you may not even need the asset pipeline. This is mostly relevant
|
|
27
32
|
- [Webpack Configuration](#webpack-configuration)
|
28
33
|
- [Custom Rails environments](#custom-rails-environments)
|
29
34
|
- [Upgrading](#upgrading)
|
30
|
-
- [Yarn Integrity](#yarn-integrity)
|
31
35
|
- [Integrations](#integrations)
|
32
|
-
- [React](#react)
|
33
|
-
- [Angular with TypeScript](#angular-with-typescript)
|
34
|
-
- [Vue](#vue)
|
35
|
-
- [Elm](#elm)
|
36
|
-
- [Stimulus](#stimulus)
|
37
|
-
- [
|
38
|
-
- [
|
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)
|
39
45
|
- [Paths](#paths)
|
40
46
|
- [Resolved](#resolved)
|
41
47
|
- [Watched](#watched)
|
@@ -46,29 +52,26 @@ in which case you may not even need the asset pipeline. This is mostly relevant
|
|
46
52
|
|
47
53
|
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
48
54
|
|
49
|
-
|
50
55
|
## Prerequisites
|
51
56
|
|
52
|
-
|
53
|
-
|
54
|
-
|
55
|
-
|
56
|
-
|
57
|
+
- Ruby 2.4+
|
58
|
+
- Rails 5.2+
|
59
|
+
- Node.js 10.17.0+
|
60
|
+
- Yarn 1.x+
|
57
61
|
|
58
62
|
## Features
|
59
63
|
|
60
|
-
|
61
|
-
|
62
|
-
|
63
|
-
|
64
|
-
|
65
|
-
|
66
|
-
|
67
|
-
|
68
|
-
|
69
|
-
|
70
|
-
|
71
|
-
|
64
|
+
- [webpack 4.x.x](https://webpack.js.org/)
|
65
|
+
- ES6 with [babel](https://babeljs.io/)
|
66
|
+
- Automatic code splitting using multiple entry points
|
67
|
+
- Stylesheets - Sass and CSS
|
68
|
+
- Images and fonts
|
69
|
+
- PostCSS - Auto-Prefixer
|
70
|
+
- Asset compression, source-maps, and minification
|
71
|
+
- CDN support
|
72
|
+
- React, Angular, Elm and Vue support out-of-the-box
|
73
|
+
- Rails view helpers
|
74
|
+
- Extensible and configurable
|
72
75
|
|
73
76
|
## Installation
|
74
77
|
|
@@ -84,11 +87,12 @@ Or add it to your `Gemfile`:
|
|
84
87
|
|
85
88
|
```ruby
|
86
89
|
# Gemfile
|
87
|
-
gem 'webpacker', '~>
|
90
|
+
gem 'webpacker', '~> 5.x'
|
88
91
|
|
89
92
|
# OR if you prefer to use master
|
90
93
|
gem 'webpacker', git: 'https://github.com/rails/webpacker.git'
|
91
94
|
yarn add https://github.com/rails/webpacker.git
|
95
|
+
yarn add core-js regenerator-runtime
|
92
96
|
```
|
93
97
|
|
94
98
|
Finally, run the following to install Webpacker:
|
@@ -107,6 +111,12 @@ Optional: To fix ["unmet peer dependency" warnings](https://github.com/rails/web
|
|
107
111
|
yarn upgrade
|
108
112
|
```
|
109
113
|
|
114
|
+
When `package.json` and/or `yarn.lock` changes, such as when pulling down changes to your local environment in a team settings, be sure to keep your NPM packages up-to-date:
|
115
|
+
|
116
|
+
```bash
|
117
|
+
yarn install
|
118
|
+
```
|
119
|
+
|
110
120
|
### Usage
|
111
121
|
|
112
122
|
Once installed, you can start writing modern ES6-flavored JavaScript apps right away:
|
@@ -116,12 +126,22 @@ app/javascript:
|
|
116
126
|
├── packs:
|
117
127
|
│ # only webpack entry files here
|
118
128
|
│ └── application.js
|
119
|
-
└── src:
|
120
129
|
│ └── application.css
|
130
|
+
└── src:
|
131
|
+
│ └── my_component.js
|
132
|
+
└── stylesheets:
|
133
|
+
│ └── my_styles.css
|
121
134
|
└── images:
|
122
135
|
└── logo.svg
|
123
136
|
```
|
124
137
|
|
138
|
+
In `/packs/application.js`, include this at the top of the file:
|
139
|
+
|
140
|
+
```js
|
141
|
+
import 'core-js/stable'
|
142
|
+
import 'regenerator-runtime/runtime'
|
143
|
+
```
|
144
|
+
|
125
145
|
You can then link the JavaScript pack in Rails views using the `javascript_pack_tag` helper.
|
126
146
|
If you have styles imported in your pack file, you can link them by using `stylesheet_pack_tag`:
|
127
147
|
|
@@ -166,7 +186,6 @@ helper otherwise you will get duplicated chunks on the page.
|
|
166
186
|
**Note:** In order for your styles or static assets files to be available in your view,
|
167
187
|
you would need to link them in your "pack" or entry file.
|
168
188
|
|
169
|
-
|
170
189
|
### Development
|
171
190
|
|
172
191
|
Webpacker ships with two binstubs: `./bin/webpack` and `./bin/webpack-dev-server`.
|
@@ -231,7 +250,6 @@ WEBPACKER_DEV_SERVER_HOST=0.0.0.0 ./bin/webpack-dev-server
|
|
231
250
|
|
232
251
|
See [docs/webpack](docs/webpack.md) for modifying webpack configuration and loaders.
|
233
252
|
|
234
|
-
|
235
253
|
### Custom Rails environments
|
236
254
|
|
237
255
|
Out of the box Webpacker ships with - development, test and production environments in `config/webpacker.yml` however, in most production apps extra environments are needed as part of deployment workflow. Webpacker supports this out of the box from version 3.4.0+ onwards.
|
@@ -281,7 +299,6 @@ bundle exec rails assets:precompile
|
|
281
299
|
bundle exec rails webpacker:compile
|
282
300
|
```
|
283
301
|
|
284
|
-
|
285
302
|
### Upgrading
|
286
303
|
|
287
304
|
You can run following commands to upgrade Webpacker to the latest stable version. This process involves upgrading the gem and related JavaScript packages:
|
@@ -296,167 +313,23 @@ yarn upgrade webpack-dev-server --latest
|
|
296
313
|
yarn add @rails/webpacker@next
|
297
314
|
```
|
298
315
|
|
299
|
-
### Yarn Integrity
|
300
|
-
|
301
|
-
By default, in development, webpacker runs a yarn integrity check to ensure that all local JavaScript packages are up-to-date. This is similar to what bundler does currently in Rails, but for JavaScript packages. If your system is out of date, then Rails will not initialize. You will be asked to upgrade your local JavaScript packages by running `yarn install`.
|
302
|
-
|
303
|
-
To turn off this option, you will need to change the default setting in `config/webpacker.yml`:
|
304
|
-
|
305
|
-
```yaml
|
306
|
-
# config/webpacker.yml
|
307
|
-
development:
|
308
|
-
...
|
309
|
-
# Verifies that correct packages and versions are installed by inspecting package.json, yarn.lock, and node_modules
|
310
|
-
check_yarn_integrity: false
|
311
|
-
```
|
312
|
-
|
313
|
-
You may also turn on this feature by adding the config option for any Rails environment in `config/webpacker.yml`:
|
314
|
-
|
315
|
-
```yaml
|
316
|
-
check_yarn_integrity: true
|
317
|
-
```
|
318
|
-
|
319
316
|
## Integrations
|
320
317
|
|
321
|
-
Webpacker ships with basic out-of-the-box integration
|
322
|
-
You can see a list of available commands/tasks by running `bundle exec rails webpacker`:
|
323
|
-
|
324
|
-
### React
|
325
|
-
|
326
|
-
To use Webpacker with [React](https://facebook.github.io/react/), create a
|
327
|
-
new Rails 5.1+ app using `--webpack=react` option:
|
328
|
-
|
329
|
-
```bash
|
330
|
-
# Rails 5.1+
|
331
|
-
rails new myapp --webpack=react
|
332
|
-
```
|
333
|
-
|
334
|
-
(or run `bundle exec rails webpacker:install:react` in an existing Rails app already
|
335
|
-
setup with Webpacker).
|
336
|
-
|
337
|
-
The installer will add all relevant dependencies using Yarn, changes
|
338
|
-
to the configuration files, and an example React component to your
|
339
|
-
project in `app/javascript/packs` so that you can experiment with React right away.
|
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`.
|
340
319
|
|
320
|
+
Included install integrations:
|
341
321
|
|
342
|
-
|
343
|
-
|
344
|
-
|
345
|
-
|
346
|
-
|
347
|
-
|
348
|
-
|
349
|
-
|
350
|
-
|
351
|
-
|
352
|
-
(or run `bundle exec rails webpacker:install:angular` on a Rails app already
|
353
|
-
setup with Webpacker).
|
354
|
-
|
355
|
-
The installer will add the TypeScript and Angular core libraries using Yarn alongside
|
356
|
-
a few changes to the configuration files. An example component written in
|
357
|
-
TypeScript will also be added to your project in `app/javascript` so that
|
358
|
-
you can experiment with Angular right away.
|
359
|
-
|
360
|
-
By default, Angular uses a JIT compiler for development environment. This
|
361
|
-
compiler is not compatible with restrictive CSP (Content Security
|
362
|
-
Policy) environments like Rails 5.2+. You can use Angular AOT compiler
|
363
|
-
in development with the [@ngtools/webpack](https://www.npmjs.com/package/@ngtools/webpack#usage) plugin.
|
364
|
-
|
365
|
-
Alternatively if you're using Rails 5.2+ you can enable `unsafe-eval` rule for your
|
366
|
-
development environment. This can be done in the `config/initializers/content_security_policy.rb`
|
367
|
-
with the following code:
|
368
|
-
|
369
|
-
```ruby
|
370
|
-
Rails.application.config.content_security_policy do |policy|
|
371
|
-
if Rails.env.development?
|
372
|
-
policy.script_src :self, :https, :unsafe_eval
|
373
|
-
else
|
374
|
-
policy.script_src :self, :https
|
375
|
-
end
|
376
|
-
end
|
377
|
-
```
|
378
|
-
|
379
|
-
|
380
|
-
### Vue
|
381
|
-
|
382
|
-
To use Webpacker with [Vue](https://vuejs.org/), create a
|
383
|
-
new Rails 5.1+ app using `--webpack=vue` option:
|
384
|
-
|
385
|
-
```bash
|
386
|
-
# Rails 5.1+
|
387
|
-
rails new myapp --webpack=vue
|
388
|
-
```
|
389
|
-
(or run `bundle exec rails webpacker:install:vue` on a Rails app already setup with Webpacker).
|
390
|
-
|
391
|
-
The installer will add Vue and its required libraries using Yarn alongside
|
392
|
-
automatically applying changes needed to the configuration files. An example component will
|
393
|
-
be added to your project in `app/javascript` so that you can experiment with Vue right away.
|
394
|
-
|
395
|
-
If you're using Rails 5.2+ you'll need to enable `unsafe-eval` rule for your development environment.
|
396
|
-
This can be done in the `config/initializers/content_security_policy.rb` with the following
|
397
|
-
configuration:
|
398
|
-
|
399
|
-
```ruby
|
400
|
-
Rails.application.config.content_security_policy do |policy|
|
401
|
-
if Rails.env.development?
|
402
|
-
policy.script_src :self, :https, :unsafe_eval
|
403
|
-
else
|
404
|
-
policy.script_src :self, :https
|
405
|
-
end
|
406
|
-
end
|
407
|
-
```
|
408
|
-
You can read more about this in the [Vue docs](https://vuejs.org/v2/guide/installation.html#CSP-environments).
|
409
|
-
|
410
|
-
|
411
|
-
### Elm
|
412
|
-
|
413
|
-
To use Webpacker with [Elm](http://elm-lang.org), create a
|
414
|
-
new Rails 5.1+ app using `--webpack=elm` option:
|
415
|
-
|
416
|
-
```
|
417
|
-
# Rails 5.1+
|
418
|
-
rails new myapp --webpack=elm
|
419
|
-
```
|
420
|
-
|
421
|
-
(or run `bundle exec rails webpacker:install:elm` on a Rails app already setup with Webpacker).
|
422
|
-
|
423
|
-
The Elm library and its core packages will be added via Yarn and Elm.
|
424
|
-
An example `Main.elm` app will also be added to your project in `app/javascript`
|
425
|
-
so that you can experiment with Elm right away.
|
426
|
-
|
427
|
-
### Stimulus
|
428
|
-
|
429
|
-
To use Webpacker with [Stimulus](http://stimulusjs.org), create a
|
430
|
-
new Rails 5.1+ app using `--webpack=stimulus` option:
|
431
|
-
|
432
|
-
```
|
433
|
-
# Rails 5.1+
|
434
|
-
rails new myapp --webpack=stimulus
|
435
|
-
```
|
436
|
-
|
437
|
-
(or run `bundle exec rails webpacker:install:stimulus` on a Rails app already setup with Webpacker).
|
438
|
-
|
439
|
-
Please read [The Stimulus Handbook](https://stimulusjs.org/handbook/introduction) or learn more about its source code at https://github.com/stimulusjs/stimulus
|
440
|
-
|
441
|
-
### CoffeeScript
|
442
|
-
|
443
|
-
To add [CoffeeScript](http://coffeescript.org/) support,
|
444
|
-
run `bundle exec rails webpacker:install:coffee` on a Rails app already
|
445
|
-
setup with Webpacker.
|
446
|
-
|
447
|
-
An example `hello_coffee.coffee` file will also be added to your project
|
448
|
-
in `app/javascript/packs` so that you can experiment with CoffeeScript right away.
|
449
|
-
|
450
|
-
### Erb
|
451
|
-
|
452
|
-
To add [Erb](https://apidock.com/ruby/ERB) support in your JS templates,
|
453
|
-
run `bundle exec rails webpacker:install:erb` on a Rails app already
|
454
|
-
setup with Webpacker.
|
455
|
-
|
456
|
-
An example `hello_erb.js.erb` file will also be added to your project
|
457
|
-
in `app/javascript/packs` so that you can experiment with Erb-flavoured
|
458
|
-
javascript right away.
|
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)
|
459
331
|
|
332
|
+
See [Integrations](./docs/integrations.md) for further details.
|
460
333
|
|
461
334
|
## Paths
|
462
335
|
|
@@ -493,17 +366,16 @@ development:
|
|
493
366
|
|
494
367
|
If you have `hmr` turned to true, then the `stylesheet_pack_tag` generates no output, as you will want to configure your styles to be inlined in your JavaScript for hot reloading. During production and testing, the `stylesheet_pack_tag` will create the appropriate HTML tags.
|
495
368
|
|
496
|
-
|
497
369
|
### Resolved
|
498
370
|
|
499
371
|
If you are adding Webpacker to an existing app that has most of the assets inside
|
500
372
|
`app/assets` or inside an engine, and you want to share that
|
501
|
-
with webpack modules, you can use the `
|
373
|
+
with webpack modules, you can use the `additional_paths`
|
502
374
|
option available in `config/webpacker.yml`. This lets you
|
503
375
|
add additional paths that webpack should lookup when resolving modules:
|
504
376
|
|
505
377
|
```yml
|
506
|
-
|
378
|
+
additional_paths: ['app/assets']
|
507
379
|
```
|
508
380
|
|
509
381
|
You can then import these items inside your modules like so:
|
@@ -518,35 +390,38 @@ import 'images/rails.png'
|
|
518
390
|
will make the compilation slow, consider adding specific paths instead of
|
519
391
|
whole parent directory if you just need to reference one or two modules
|
520
392
|
|
521
|
-
|
522
|
-
### Watched
|
523
|
-
|
524
|
-
By default, the lazy compilation is cached until a file is changed under your
|
525
|
-
tracked paths. You can configure which paths are tracked
|
526
|
-
by adding new paths to `watched_paths` array. This is much like Rails' `autoload_paths`:
|
527
|
-
|
528
|
-
```rb
|
529
|
-
# config/initializers/webpacker.rb
|
530
|
-
# or config/application.rb
|
531
|
-
Webpacker::Compiler.watched_paths << 'bower_components'
|
532
|
-
```
|
533
|
-
|
534
|
-
|
535
393
|
## Deployment
|
536
394
|
|
537
395
|
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).
|
538
396
|
|
397
|
+
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.
|
539
398
|
|
540
399
|
## Docs
|
541
400
|
|
542
|
-
|
543
|
-
|
401
|
+
- [Development](https://github.com/rails/webpacker#development)
|
402
|
+
- [Webpack](./docs/webpack.md)
|
403
|
+
- [Webpack-dev-server](./docs/webpack-dev-server.md)
|
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)
|
544
418
|
|
545
419
|
## Contributing
|
420
|
+
|
546
421
|
[![Code Helpers](https://www.codetriage.com/rails/webpacker/badges/users.svg)](https://www.codetriage.com/rails/webpacker)
|
547
422
|
|
548
423
|
We encourage you to contribute to Webpacker! See [CONTRIBUTING](CONTRIBUTING.md) for guidelines about how to proceed.
|
549
424
|
|
550
|
-
|
551
425
|
## License
|
426
|
+
|
552
427
|
Webpacker is released under the [MIT License](https://opensource.org/licenses/MIT).
|
data/docs/css.md
CHANGED
@@ -3,9 +3,66 @@
|
|
3
3
|
|
4
4
|
Webpacker supports importing CSS, Sass and SCSS files directly into your JavaScript files.
|
5
5
|
|
6
|
+
Importing and loading styles is a two step process:
|
7
|
+
|
8
|
+
1. You need to tell webpack which file(s) it has to compile and know how to load
|
9
|
+
|
10
|
+
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.)
|
11
|
+
|
12
|
+
2. You need to load those files in your views
|
13
|
+
|
14
|
+
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.
|
15
|
+
|
16
|
+
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.
|
17
|
+
|
6
18
|
|
7
19
|
## Import global styles into your JS app
|
8
20
|
|
21
|
+
### Importing CSS as a multi-file pack (Webpacker v5)
|
22
|
+
|
23
|
+
When you add a CSS/SCSS/SASS file to `app/javascript/packs/` directory, make sure to use the same pack name as its complementary JavaScript pack, e.g. `application.js` and `application.css`. By Webpacker convention (as of Webpacker v5), this will bundle `application.js` and `application.scss` as part of the same entry point (also described as [a multi-file entry point in the webpack docs](https://webpack.js.org/concepts/entry-points/#single-entry-shorthand-syntax)). With this approach, you can avoid importing CSS from JS, if desired.
|
24
|
+
|
25
|
+
```
|
26
|
+
app/
|
27
|
+
javascript/
|
28
|
+
packs/
|
29
|
+
application.js
|
30
|
+
application.scss
|
31
|
+
```
|
32
|
+
|
33
|
+
### Importing CSS from CSS
|
34
|
+
|
35
|
+
You can import additional CSS/SCSS/SASS files from within a CSS file:
|
36
|
+
|
37
|
+
```
|
38
|
+
app/
|
39
|
+
javascript/
|
40
|
+
stylesheets/
|
41
|
+
application.scss
|
42
|
+
posts.scss
|
43
|
+
comments.scss
|
44
|
+
```
|
45
|
+
|
46
|
+
```css
|
47
|
+
/* app/javascript/stylesheets/application.scss */
|
48
|
+
|
49
|
+
@import './posts';
|
50
|
+
@import './comments';
|
51
|
+
```
|
52
|
+
|
53
|
+
### Importing CSS provided by an NPM package from SCSS/CSS
|
54
|
+
|
55
|
+
Given your application installs an NPM package that provides CSS, such as `flatpickr`, you can import the CSS file(s) by path from the package directory within `node_modules/`:
|
56
|
+
|
57
|
+
```js
|
58
|
+
/* app/javascript/stylesheets/application.scss */
|
59
|
+
|
60
|
+
@import "flatpickr/dist/flatpickr.css"
|
61
|
+
```
|
62
|
+
|
63
|
+
|
64
|
+
### Importing CSS from JS
|
65
|
+
|
9
66
|
```sass
|
10
67
|
// app/javascript/hello_react/styles/hello-react.sass
|
11
68
|
|
@@ -30,6 +87,16 @@ const Hello = props => (
|
|
30
87
|
)
|
31
88
|
```
|
32
89
|
|
90
|
+
### Importing CSS provided by an NPM package from JS
|
91
|
+
|
92
|
+
Given your application installs an NPM package that provides CSS, such as `flatpickr`, you can import the CSS file(s) by path from the package directory within `node_modules/`. This is an alternative to importing from within a CSS file, as above:
|
93
|
+
|
94
|
+
```js
|
95
|
+
// app/javascript/packs/application.js
|
96
|
+
|
97
|
+
import "flatpickr/dist/flatpickr.css"
|
98
|
+
```
|
99
|
+
|
33
100
|
## Import scoped styles into your JS app
|
34
101
|
|
35
102
|
Stylesheets that end with `.module.*` are treated as [CSS Modules](https://github.com/css-modules/css-modules).
|
@@ -135,14 +202,14 @@ You can use Yarn to add bootstrap or any other modules available on npm:
|
|
135
202
|
yarn add bootstrap
|
136
203
|
```
|
137
204
|
|
138
|
-
Import Bootstrap and theme (optional) CSS in your app/javascript/packs/
|
205
|
+
Import Bootstrap and theme (optional) CSS in your app/javascript/packs/application.js file:
|
139
206
|
|
140
207
|
```js
|
141
208
|
import 'bootstrap/dist/css/bootstrap'
|
142
209
|
import 'bootstrap/dist/css/bootstrap-theme'
|
143
210
|
```
|
144
211
|
|
145
|
-
Or in your app/javascript/
|
212
|
+
Or in your app/javascript/packs/application.sass file:
|
146
213
|
|
147
214
|
```sass
|
148
215
|
// ~ to tell that this is not a relative import
|
@@ -201,11 +268,10 @@ const { environment } = require('@rails/webpacker')
|
|
201
268
|
|
202
269
|
// resolve-url-loader must be used before sass-loader
|
203
270
|
environment.loaders.get('sass').use.splice(-1, 0, {
|
204
|
-
loader: 'resolve-url-loader'
|
205
|
-
options: {
|
206
|
-
attempts: 1
|
207
|
-
}
|
271
|
+
loader: 'resolve-url-loader'
|
208
272
|
});
|
273
|
+
|
274
|
+
module.exports = environment
|
209
275
|
```
|
210
276
|
|
211
277
|
## Working with TypeScript
|
data/docs/deployment.md
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
# Deployment
|
2
2
|
|
3
3
|
|
4
|
-
Webpacker hooks up a new `webpacker:compile` task to `assets:precompile`, which gets run whenever you run `assets:precompile`.
|
4
|
+
Webpacker hooks up a new `webpacker:compile` task to `assets:precompile`, which gets run whenever you run `assets:precompile`.
|
5
5
|
If you are not using Sprockets `webpacker:compile` is automatically aliased to `assets:precompile`. Remember to set NODE_ENV environment variable to production during deployment or when running the rake task.
|
6
6
|
|
7
7
|
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.
|
@@ -13,37 +13,46 @@ By default the output will look like this in different environments:
|
|
13
13
|
<script src="http://localhost:8080/calendar-0bd141f6d9360cf4a7f5.js"></script>
|
14
14
|
<link rel="stylesheet" media="screen" href="http://localhost:8080/calendar-dc02976b5f94b507e3b6.css">
|
15
15
|
<!-- In production or development mode -->
|
16
|
-
<script src="/packs/calendar-0bd141f6d9360cf4a7f5.js"></script>
|
17
|
-
<link rel="stylesheet" media="screen" href="/packs/calendar-dc02976b5f94b507e3b6.css">
|
16
|
+
<script src="/packs/js/calendar-0bd141f6d9360cf4a7f5.js"></script>
|
17
|
+
<link rel="stylesheet" media="screen" href="/packs/css/calendar-dc02976b5f94b507e3b6.css">
|
18
18
|
```
|
19
19
|
|
20
20
|
|
21
21
|
## Heroku
|
22
22
|
|
23
|
-
|
24
|
-
Webpacker so all you would need to do:
|
23
|
+
In order for your Webpacker app to run on Heroku, you'll need to do a bit of configuration before hand.
|
25
24
|
|
26
|
-
```
|
27
|
-
heroku create
|
25
|
+
```
|
26
|
+
heroku create my-webpacker-heroku-app
|
28
27
|
heroku addons:create heroku-postgresql:hobby-dev
|
28
|
+
heroku buildpacks:add heroku/nodejs
|
29
|
+
heroku buildpacks:add heroku/ruby
|
29
30
|
git push heroku master
|
30
31
|
```
|
31
32
|
|
33
|
+
We're essentially doing the following here:
|
34
|
+
|
35
|
+
* Creating an app on Heroku
|
36
|
+
* Creating a Postgres database for the app (this is assuming that you're using Heroku Postgres for your app)
|
37
|
+
* Adding the Heroku NodeJS and Ruby buildpacks for your app. This allows the `npm` or `yarn` executables to properly function when compiling your app - as well as Ruby.
|
38
|
+
* Pushing our code to Heroku and kicking off the deployment
|
39
|
+
|
32
40
|
|
33
41
|
## Nginx
|
34
42
|
|
35
43
|
Webpacker doesn't serve anything in production. You’re expected to configure your web server to serve files in public/ directly.
|
36
44
|
|
37
|
-
Some servers support sending precompressed versions of files
|
45
|
+
Some servers support sending precompressed versions of files when they're available. For example, nginx offers a `gzip_static` directive that serves files with the `.gz` extension to supported clients. With an optional module, nginx can also serve Brotli compressed files with the `.br` extension (see below for installation and configuration instructions).
|
38
46
|
|
39
47
|
Here's a sample nginx site config for a Rails app using Webpacker:
|
40
48
|
|
41
49
|
```nginx
|
42
50
|
upstream app {
|
43
|
-
#
|
51
|
+
# server unix:///path/to/app/tmp/puma.sock;
|
44
52
|
}
|
45
53
|
|
46
54
|
server {
|
55
|
+
listen 80;
|
47
56
|
server_name www.example.com;
|
48
57
|
root /path/to/app/public;
|
49
58
|
|
@@ -61,13 +70,34 @@ server {
|
|
61
70
|
try_files $uri @app;
|
62
71
|
}
|
63
72
|
|
64
|
-
location
|
73
|
+
location = /favicon.ico { access_log off; log_not_found off; }
|
74
|
+
location = /robots.txt { access_log off; log_not_found off; }
|
75
|
+
|
76
|
+
location ~ /\.(?!well-known).* {
|
77
|
+
deny all;
|
78
|
+
}
|
79
|
+
|
80
|
+
location ~ ^/(assets|packs)/ {
|
65
81
|
gzip_static on;
|
82
|
+
brotli_static on; # Optional, see below
|
66
83
|
expires max;
|
84
|
+
add_header Cache-Control public;
|
67
85
|
}
|
68
86
|
}
|
69
87
|
```
|
70
88
|
|
89
|
+
### Installing the ngx_brotli module
|
90
|
+
|
91
|
+
If you want to serve Brotli compressed files with nginx, you will need to install the `nginx_brotli` module. Installation instructions from source can be found in the official [google/ngx_brotli](https://github.com/google/ngx_brotli) git repository. Alternatively, depending on your platform, the module might be available via a pre-compiled package.
|
92
|
+
|
93
|
+
Once installed, you need to load the module. As we want to serve the pre-compressed files, we only need the static module. Add the following line to your `nginx.conf` file and reload nginx:
|
94
|
+
|
95
|
+
```
|
96
|
+
load_module modules/ngx_http_brotli_static_module.so;
|
97
|
+
```
|
98
|
+
|
99
|
+
Now, you can set `brotli_static on;` in your nginx site config, as per the config in the last section above.
|
100
|
+
|
71
101
|
## CDN
|
72
102
|
|
73
103
|
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
|
@@ -98,4 +128,3 @@ namespace :deploy do
|
|
98
128
|
end
|
99
129
|
end
|
100
130
|
```
|
101
|
-
|