webpacker 5.2.1 → 6.0.0.beta

data/docs/css.md

@@ -1,308 +0,0 @@
-# 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
-
-### Importing CSS as a multi-file pack (Webpacker v5)
-
-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.
-
-```
-app/
-  javascript/
-    packs/
-      application.js
-      application.scss
-```
-
-### Importing CSS from CSS
-
-You can import additional CSS/SCSS/SASS files from within a CSS file:
-
-```
-app/
-  javascript/
-    stylesheets/
-      application.scss
-      posts.scss
-      comments.scss
-```
-
-```css
-/* app/javascript/stylesheets/application.scss */
-
-@import './posts';
-@import './comments';
-```
-
-### Importing CSS provided by an NPM package from SCSS/CSS
-
-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/`:
-
-```js
-/* app/javascript/stylesheets/application.scss */
-
-@import "flatpickr/dist/flatpickr.css"
-```
-
-
-### Importing CSS from JS
-
-```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>
-)
-```
-
-### Importing CSS provided by an NPM package from JS
-
-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:
-
-```js
-// app/javascript/packs/application.js
-
-import "flatpickr/dist/flatpickr.css"
-```
-
-## 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/application.js file:
-
-```js
-import 'bootstrap/dist/css/bootstrap'
-import 'bootstrap/dist/css/bootstrap-theme'
-```
-
-Or in your app/javascript/packs/application.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;
-  }
-});
-```

data/docs/deployment.md

@@ -1,130 +0,0 @@
-# Deployment
-
-
-Webpacker hooks up a new `webpacker:compile` task to `assets:precompile`, which gets run whenever you run `assets:precompile`.
-If you are not using Sprockets `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.
-
-The `javascript_pack_tag` and `stylesheet_pack_tag` helper method will automatically insert the correct HTML tag for compiled pack. Just like the asset pipeline does it.
-
-By default the output will look like this in different environments:
-
-```html
-  <!-- In development mode with webpack-dev-server -->
-  <script src="http://localhost:8080/calendar-0bd141f6d9360cf4a7f5.js"></script>
-  <link rel="stylesheet" media="screen" href="http://localhost:8080/calendar-dc02976b5f94b507e3b6.css">
-  <!-- In production or development mode -->
-  <script src="/packs/js/calendar-0bd141f6d9360cf4a7f5.js"></script>
-  <link rel="stylesheet" media="screen" href="/packs/css/calendar-dc02976b5f94b507e3b6.css">
-```
-
-
-## Heroku
-
-In order for your Webpacker app to run on Heroku, you'll need to do a bit of configuration before hand.
-
-```
-heroku create my-webpacker-heroku-app
-heroku addons:create heroku-postgresql:hobby-dev
-heroku buildpacks:add heroku/nodejs
-heroku buildpacks:add heroku/ruby
-git push heroku master
-```
-
-We're essentially doing the following here:
-
-* Creating an app on Heroku
-* Creating a Postgres database for the app (this is assuming that you're using Heroku Postgres for your app)
-* 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.
-* Pushing our code to Heroku and kicking off the deployment
-
-
-## Nginx
-
-Webpacker doesn't serve anything in production. You’re expected to configure your web server to serve files in public/ directly.
-
-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).
-
-Here's a sample nginx site config for a Rails app using Webpacker:
-
-```nginx
-upstream app {
-  # server unix:///path/to/app/tmp/puma.sock;
-}
-
-server {
-  listen 80;
-  server_name www.example.com;
-  root /path/to/app/public;
-
-  location @app {
-    proxy_pass http://app;
-    proxy_redirect off;
-
-    proxy_set_header Host $host;
-    proxy_set_header X-Real-IP $remote_addr;
-    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_set_header X-Forwarded-Proto $scheme;
-  }
-
-  location / {
-    try_files $uri @app;
-  }
-
-  location = /favicon.ico { access_log off; log_not_found off; }
-  location = /robots.txt  { access_log off; log_not_found off; }
-
-  location ~ /\.(?!well-known).* {
-    deny all;
-  }
-
-  location ~ ^/(assets|packs)/ {
-    gzip_static on;
-    brotli_static on; # Optional, see below
-    expires max;
-    add_header Cache-Control public;
-  }
-}
-```
-
-### Installing the ngx_brotli module
-
-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.
-
-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:
-
-```
-load_module modules/ngx_http_brotli_static_module.so;
-```
-
-Now, you can set `brotli_static on;` in your nginx site config, as per the config in the last section above.
-
-## CDN
-
-Webpacker out-of-the-box provides CDN support using your Rails app `config.action_controller.asset_host` setting. If you already have [CDN](http://guides.rubyonrails.org/asset_pipeline.html#cdns) added in your Rails app
-you don't need to do anything extra for Webpacker, it just works.
-
-## Capistrano
-
-### Assets compiling on every deployment even if JavaScript and CSS files are not changed
-
-Make sure you have `public/packs` and `node_modules` in `:linked_dirs`
-
-```ruby
-append :linked_dirs, "log", "tmp/pids", "tmp/cache", "tmp/sockets", "public/packs", ".bundle", "node_modules"
-```
-
-If you have `node_modules` added to `:linked_dirs` you'll need to run yarn install before `deploy:assets:precompile`, so you can add this code snippet at the bottom deploy.rb
-
-```ruby
-before "deploy:assets:precompile", "deploy:yarn_install"
-namespace :deploy do
-  desc "Run rake yarn install"
-  task :yarn_install do
-    on roles(:web) do
-      within release_path do
-        execute("cd #{release_path} && yarn install --silent --no-progress --no-audit --no-optional")
-      end
-    end
-  end
-end
-```

data/docs/docker.md

@@ -1,68 +0,0 @@
-# Docker
-
-To setup webpacker with a dockerized Rails application.
-
-First, add a new service for webpacker in docker-compose.yml:
-
-```Dockerfile
-version: '3'
-services:
-  webpacker:
-    build: .
-    environment:
-      - NODE_ENV=development
-      - RAILS_ENV=development
-      - WEBPACKER_DEV_SERVER_HOST=0.0.0.0
-    command: ./bin/webpack-dev-server
-    volumes:
-      - .:/webpacker-example-app
-    ports:
-      - '3035:3035'
-```
-
-add nodejs and yarn as dependencies in Dockerfile,
-
-```dockerfile
-FROM ruby:2.4.1
-
-RUN apt-get update -qq && apt-get install -y build-essential nodejs \
- && rm -rf /var/lib/apt/lists/* \
- && curl -o- -L https://yarnpkg.com/install.sh | bash
-
-# Rest of the commands....
-```
-
-Please note: if using `assets:precompile` in the Dockerfile or have issues with the snippet above then try:
-
-```dockerfile
-FROM ruby:2.4.1
-
-RUN curl -sL https://deb.nodesource.com/setup_8.x | bash \
- && apt-get update && apt-get install -y nodejs && rm -rf /var/lib/apt/lists/* \
- && curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add - \
- && echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list \
- && apt-get update && apt-get install -y yarn && rm -rf /var/lib/apt/lists/*
-
-# Rest of the commands....
-```
-
-then add the webpacker host name environment variable to the web/app service:
-
-```Dockerfile
-  web:
-    build:
-      context: .
-    command: bash -c "rm -f tmp/pids/server.pid && bundle exec rails s -p 3000 -b '0.0.0.0'"
-    volumes:
-      - .:/usr/src/app
-    ports:
-      - "3000:3000"
-    environment:
-      - WEBPACKER_DEV_SERVER_HOST=webpacker
-```
-
-Lastly, rebuild your container:
-
-```bash
-docker-compose up --build
-```