From 81918057db91005cca497f12ec5c5b8f5d779e4e Mon Sep 17 00:00:00 2001 From: Gaurav Tiwari Date: Mon, 11 Dec 2017 11:28:00 +0000 Subject: [PATCH] Prepare docs for new release (#1076) --- CHANGELOG.md | 16 +++++- docs/assets.md | 2 +- docs/css.md | 19 ++++++- docs/deployment.md | 38 +++++++++++++ docs/docker.md | 49 ++++++++++++++++ docs/webpack-dev-server.md | 2 +- docs/webpack.md | 114 +++++++++++++++++++++++++++++++------ 7 files changed, 216 insertions(+), 24 deletions(-) create mode 100644 docs/docker.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 0fd0c5795..1ef6b9f9c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,7 +25,7 @@ const jsonLoader = { loader: 'json-loader' } -environment.loaders.set('json', jsonLoader) +environment.loaders.append('json', jsonLoader) environment.loaders.prepend('json', jsonLoader) environment.loaders.insert('json', jsonLoader, { after: 'style' } ) environment.loaders.insert('json', jsonLoader, { before: 'babel' } ) @@ -36,7 +36,7 @@ manifestPlugin.opts.writeToFileEmit = false // Update coffee loader to use coffeescript 2 const babelLoader = environment.loaders.get('babel') -environment.loaders.set('coffee', { +environment.loaders.insert('coffee', { test: /\.coffee(\.erb)?$/, use: babelLoader.use.concat(['coffee-loader']) }, { before: 'json' }) @@ -45,7 +45,7 @@ environment.loaders.set('coffee', { - Expose `resolve.modules` paths like loaders and plugins ```js -environment.resolvedModules.set('vendor', 'vendor') +environment.resolvedModules.append('vendor', 'vendor') ``` - Enable sourcemaps in `style` and `css` loader @@ -75,6 +75,13 @@ watch_options: ignored: /node_modules/ ``` +- `pretty` option to disable/enable color and progress output when running dev server + +```yml +dev_server: + pretty: false +``` + - Enforce deterministic loader order in desc order, starts processing from top to bottom - Enforce the entire path of all required modules match the exact case of the actual path on disk using [case sensitive paths plugin](https://github.com/Urthen/case-sensitive-paths-webpack-plugin). @@ -97,6 +104,9 @@ WEBPACKER_PRECOMPILE=false bundle exec rails assets:precompile - Use `WEBPACKER_ASSET_HOST` instead of `ASSET_HOST` for CDN +- Alias `webpacker:compile` task to `assets:precompile` if is not defined so it works +without sprockets + ## [3.0.2] - 2017-10-04 diff --git a/docs/assets.md b/docs/assets.md index f4bd4f55d..3f0fec609 100644 --- a/docs/assets.md +++ b/docs/assets.md @@ -42,7 +42,7 @@ It's possible to link to assets that have been precompiled by Sprockets. Add the <%# app/javascript/my_pack/example.js.erb %> <% helpers = ActionController::Base.helpers %> -var railsImagePath = "<%= helpers.image_path('rails.png') %>" +const railsImagePath = "<%= helpers.image_path('rails.png') %>" ``` This is enabled by the `rails-erb-loader` loader rule in `config/webpack/loaders/erb.js`. diff --git a/docs/css.md b/docs/css.md index 741e06a02..987c25a8f 100644 --- a/docs/css.md +++ b/docs/css.md @@ -89,6 +89,23 @@ file for the entry point. Loading the stylesheet will also load the CSS for any nested components. ```erb -<%= stylesheet_pack_tag 'hello_vue' %> +<%= 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') + +const sassLoader = environment.loaders.get('sass') +sassLoader.use.push({ loader: 'resolve-url-loader' }) +``` diff --git a/docs/deployment.md b/docs/deployment.md index 5310a96d3..89a640d63 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -30,6 +30,44 @@ git push heroku master ``` +## 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 with the `.gz` extension when they're available. For example, nginx offers a `gzip_static` directive. + +Here's a sample nginx site config for a Rails app using Webpacker: + +```nginx +upstream app { + # ... +} + +server { + 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 ^~ /packs/ { + gzip_static on; + expires max; + } +} +``` + ## 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 diff --git a/docs/docker.md b/docs/docker.md new file mode 100644 index 000000000..6593e89fe --- /dev/null +++ b/docs/docker.md @@ -0,0 +1,49 @@ +# Docker + +To setup webpacker with a dockerized Rails application is trivial. + +First, add a new service for webpacker in docker-compose.yml: + +```Dockerfile +version: '3' +services: + webpacker: + build: . + env_file: + - '.env.docker' + command: bundle exec 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 + +RUN curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add - +RUN curl -sL https://deb.nodesource.com/setup_8.x | bash +RUN echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list + +RUN apt-get install -y nodejs +RUN apt-get update && apt-get install yarn + +# Rest of the commands.... +``` + +and create an env file to load environment variables from: + +```env +NODE_ENV=development +RAILS_ENV=development +WEBPACKER_DEV_SERVER_HOST: 0.0.0.0 +``` + +Lastly, rebuild your container: + +```bash +docker-compose up --build +``` diff --git a/docs/webpack-dev-server.md b/docs/webpack-dev-server.md index a4944e9aa..09d557182 100644 --- a/docs/webpack-dev-server.md +++ b/docs/webpack-dev-server.md @@ -1,4 +1,4 @@ -# webpack Dev Server +# webpack-dev-server ## HTTPS diff --git a/docs/webpack.md b/docs/webpack.md index 911994e77..c179a4074 100644 --- a/docs/webpack.md +++ b/docs/webpack.md @@ -28,25 +28,32 @@ module.exports = { } } -// config/webpack/development.js -const merge = require('webpack-merge') +// config/webpack/environment.js const environment = require('./environment') const customConfig = require('./custom') -module.exports = merge(environment.toWebpackConfig(), customConfig) -``` +// Set nested object prop using path notation +environment.config.set('resolve.extensions', ['.foo', '.bar']) +environment.config.set('output.filename', '[name].js') -If you need access to configs within Webpacker's configuration, you can import them like this: -```js -const config = require('@rails/webpacker/package/config'); -const asset_host = require('@rails/webpacker/package/asset_host'); +// Merge custom config +environment.config.merge(customConfig) + +// Delete a property +environment.config.delete('output.chunkFilename') -console.log(asset_host.publicPathWithHost); +module.exports = environment ``` -**Note:** You will have to merge custom config to all env where you want that config -to be available. In above case, it will be applied to development environment. +If you need access to configs within Webpacker's configuration, +you can import them like so: +```js +const { config, asset_host } = require('@rails/webpacker') + +console.log(asset_host.publicPathWithHost) +console.log(config.source_path) +``` ## Loaders @@ -61,11 +68,18 @@ yarn add json-loader // config/webpack/environment.js const { environment } = require('@rails/webpacker') -environment.loaders.set('json', { +environment.loaders.append('json', { test: /\.json$/, use: 'json-loader' }) +// Insert json loader at the top of list +environment.loaders.prepend('json', jsonLoader) + +// Insert json loader after/before a given loader +environment.loaders.insert('json', jsonLoader, { after: 'style'} ) +environment.loaders.insert('json', jsonLoader, { before: 'babel'} ) + module.exports = environment ``` @@ -79,13 +93,58 @@ the `babel` loader as an example: // config/webpack/environment.js const { environment } = require('@rails/webpacker') -// Update an option directly const babelLoader = environment.loaders.get('babel') babelLoader.options.cacheDirectory = false module.exports = environment ``` +### Coffeescript 2 + +Out of the box webpacker supports coffeescript 1, +but here is how you can use Coffeescript 2: + +``` +yarn add coffeescript@2.0.1 +``` + +```js +// config/webpack/environment.js +const { environment } = require('@rails/webpacker') + +const babelLoader = environment.loaders.get('babel') + +// Replace existing coffee loader with CS2 version +environment.loaders.insert('coffee', { + test: /\.coffee(\.erb)?$/, + use: babelLoader.use.concat(['coffee-loader']) +}) + +module.exports = environment +``` + +### React SVG loader + +To use react svg loader, you should append svg loader before file loader: + +```js +const { environment } = require('@rails/webpacker') + +const babelLoader = environment.loaders.get('babel') + +environment.loaders.insert('svg', { + test: /\.svg$/, + use: babelLoader.use.concat([ + { + loader: 'react-svg-loader', + options: { + jsx: true // true outputs JSX tags + } + } + ]) +}, { before: 'file' }) +``` + ### Overriding Loader Options in webpack 3+ (for CSS Modules etc.) In webpack 3+, if you'd like to specify additional or different options for a loader, edit `config/webpack/environment.js` and provide an options object to override. This is similar to the technique shown above, but the following example shows specifically how to apply CSS Modules, which is what you may be looking for: @@ -126,10 +185,11 @@ const { environment } = require('@rails/webpacker') const webpack = require('webpack') // Get a pre-configured plugin -environment.plugins.get('ExtractText') // Is an ExtractTextPlugin instance +const manifestPlugin = environment.plugins.get('Manifest') +manifestPlugin.opts.writeToFileEmit = false // Add an additional plugin of your choosing : ProvidePlugin -environment.plugins.set( +environment.plugins.prepend( 'Provide', new webpack.ProvidePlugin({ $: 'jquery', @@ -143,9 +203,27 @@ environment.plugins.set( }) ) +// Insert before a given plugin +environment.plugins.insert('CommonChunkVendor', + new webpack.optimize.CommonsChunkPlugin({ + name: 'vendor', // Vendor code + minChunks: (module) => module.context && module.context.indexOf('node_modules') !== -1 + }) +, { before: 'manifest' }) + module.exports = environment ``` +## Resolved modules + +To add new paths to `resolve.modules`, the API is same as loaders and plugins: + +```js +const { environment } = require('@rails/webpacker') + +// Resolved modules list API - prepend, append, insert +environment.resolvedModules.append('vendor', 'vendor') +``` ### Add common chunks @@ -156,18 +234,18 @@ Add the plugins in `config/webpack/environment.js`: ```js const webpack = require('webpack') -environment.plugins.set( +environment.plugins.append( 'CommonsChunkVendor', new webpack.optimize.CommonsChunkPlugin({ name: 'vendor', minChunks: (module) => { // this assumes your vendor imports exist in the node_modules directory - return module.context && module.context.indexOf('node_modules') !== -1; + return module.context && module.context.indexOf('node_modules') !== -1 } }) ) -environment.plugins.set( +environment.plugins.append( 'CommonsChunkManifest', new webpack.optimize.CommonsChunkPlugin({ name: 'manifest',