From ebc4781282a8ae712729c3df4a47a388b2018f61 Mon Sep 17 00:00:00 2001 From: Hisako Shirasaki Date: Tue, 30 May 2017 14:40:28 +0900 Subject: [PATCH 1/3] Translate build-config.md via GitLocalize --- ja/build-config.md | 202 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 202 insertions(+) create mode 100644 ja/build-config.md diff --git a/ja/build-config.md b/ja/build-config.md new file mode 100644 index 00000000..8ce73b5a --- /dev/null +++ b/ja/build-config.md @@ -0,0 +1,202 @@ +# ビルド設定 + +クライアントサイドで完結するプロジェクトのwebpack設定は既に知っての通りでしょう。 SSRプロジェクトにおいても大枠は似たようなものですが、設定ファイルを3つのファイル( *ベース*、 *クライアント* 、 *サーバ* )に分けることを提案しています。 ベース設定は出力パス、エイリアス、ローダーのような両方の環境(TO DO：どれとどれ?)に共有される設定を含み、サーバ設定とクライアント設定は単純に、 [webpack-merge](https://github.com/survivejs/webpack-merge)を使って、ベース設定を拡張することができるものです。 + +## サーバ設定 + +サーバ設定は`createBundleRenderer`に渡されるサーババンドルを生成するために作られるもので、次のようになります: + +```js +const merge = require('webpack-merge') +const nodeExternals = require('webpack-node-externals') +const baseConfig = require('./webpack.base.config.js') +const VueSSRServerPlugin = require('vue-server-renderer/server-plugin') +module.exports = merge(baseConfig, { + // Point entry to your app's server entry file + entry: '/path/to/entry-server.js', + // This allows webpack to handle dynamic imports in a Node-appropriate + // fashion, and also tells `vue-loader` to emit server-oriented code when + // compiling Vue components. + target: 'node', + // For bundle renderer source map support + devtool: 'source-map', + // This tells the server bundle to use Node-style exports + output: { + libraryTarget: 'commonjs2' + }, + // https://webpack.js.org/configuration/externals/#function + // https://github.com/liady/webpack-node-externals + // Externalize app dependencies. This makes the server build much faster + // and generates a smaller bundle file. + externals: nodeExternals({ + // do not externalize dependencies that need to be processed by webpack. + // you can add more file types here e.g. raw *.vue files + // you should also whitelist deps that modifies `global` (e.g. polyfills) + whitelist: /\.css$/ + }), + // This is the plugin that turns the entire output of the server build + // into a single JSON file. The default file name will be + // `vue-ssr-server-bundle.json` + plugins: [ + new VueSSRServerPlugin() + ] +}) +``` + + `vue-ssr-server-bundle.json`が生成されたら、ファイルパスを `createBundleRenderer`に渡すだけです: + +```js +const { createBundleRenderer } = require('vue-server-renderer') +const renderer = createBundleRenderer('/path/to/vue-ssr-server-bundle.json', { + // ...other renderer options +}) +``` + +別の方法として、 バンドルをオブジェクトとして`createBundleRenderer`に渡すことも可能で、これはホットリロード開発中に有効です。 参考として [HackerNewsの設定](https://github.com/vuejs/vue-hackernews-2.0/blob/master/build/setup-dev-server.js) を見てみてください。 + +### 外部警告 + + CSSファイルを`externals`オプションにホワイトリスト登録していることに注目してください。その理由は、依存関係からインポートされるCSS はwebpackによって管理されないといけないからです。 もし同じようにwebpackに依存する他のタイプのファイルをインポートしているなら、 (例： `*.vue`, `*.sass`)、 それらも同じようにホワイトリストに加えなければいけません。 + +ホワイトリスト登録する他のタイプのモジュールは、例えば `babel-polyfill`のような`global`を修正するポリフィルです。なぜなら、サーババンドルの中のコードは独自の ** `global` **オブジェクトを持っているからです。Node 7.6+を使っていればサーバに`babel-polyfill`はあまり必要ないので、単純にクライアントエントリーにインポートする方が簡単です。 + +## クライアント設定 + +クライアント設定はベース設定とほぼ同じままです。言うまでもなく、クライアント側のエントリーファイルに`entry`を示す必要があります。またそれとは別に、もし`CommonsChunkPlugin`使っていたら、それがクライアント設定だけで使われていることを確認しておかないといけません。なぜなら、サーババンドルは単一のエントリーチャンクを要求するからです。 + +### `clientManifest` の作成 + +> 必須 version 2.3.0+ + +サーババンドルに加えて、クライアントビルドマニフェストを作成することもできます。レンダラーは、クライアントマニフェストとサーババンドルでサーバ 側*と*クライアント側の両方のビルド情報を持つことになり、 レンダーされたHTMLに[preload / prefetch directives](https://css-tricks.com/prefetching-preloading-prebrowsing/)やCSSのlinkやscriptタグを自動的に挿入することができます。 + +これには2重の恩恵があります: + +1. 生成されたファイル名にハッシュがある時に、正しいURLをセットする`html-webpack-plugin` の代替になります。 +2. webpackのオンデマンドコード分割機能を利用するバンドルをレンダリングする時に、最適なチャンクがpreloaded / prefetchedされるのを保証でき、かつ、クライアントに対するウォーターフォールリクエストを避けるために、必要な非同期チャンクに``タグを挿入することができます。そのようにしてTTI (time-to-interactive)が改善します。 + +クライアントマニフェストを利用するためには、クライアント設定はこのようになります： + +```js +const webpack = require('webpack') +const merge = require('webpack-merge') +const baseConfig = require('./webpack.base.config.js') +const VueSSRClientPlugin = require('vue-server-renderer/client-plugin') +module.exports = merge(baseConfig, { + entry: '/path/to/entry-client.js', + plugins: [ + // Important: this splits the webpack runtime into a leading chunk + // so that async chunks can be injected right after it. + // this also enables better caching for your app/vendor code. + new webpack.optimize.CommonsChunkPlugin({ + name: "manifest", + minChunks: Infinity + }), + // This plugins generates `vue-ssr-client-manifest.json` in the + // output directory. + new VueSSRClientPlugin() + ] +}) +``` + +これで、作成されたクライアントマニフェストをページテンプレートと一緒に利用できるようになります。 + +```js +const { createBundleRenderer } = require('vue-server-renderer') +const template = require('fs').readFileSync('/path/to/template.html', 'utf-8') +const serverBundle = require('/path/to/vue-ssr-server-bundle.json') +const clientManifest = require('/path/to/vue-ssr-client-manifest.json') +const renderer = createBundleRenderer(serverBundle, { + template, + clientManifest +}) +``` + +この設定で、コード分割されたビルドのためにサーバ側でレンダリングされるHTMLはこのようになります(すべて自動でインジェクトされます)。 + +```html + + + + + + + + + + + +
async
+ + + + + + +` +``` + +### 手動でのアセットインジェクション + +デフォルト設定で、アセットインジェクションはあなたが作成した`template`レンダーオプションで自動に行われます。 しかし、アセットがどのようにテンプレートにインジェクトされるかをより細かくコントロールしたい時もあるでしょうし、あるいはテンプレートを使わない時もあるかもしれません。そのような場合にはレンダラーを作る時に`inject: false`を渡せば、手動でアセットインジェクションを行うことができます。 + +渡した`context`オブジェクトは`renderToString`コールバックで、 次のメソッドを持ちます: + +- `context.renderStyles()` + +これは、レンダー中に使われた`*.vue`コンポーネントから集めた全てのクリティカルCSSを含んだ`` タグを返します。詳細は [CSS Management](./css.md)の章を見てください。 + +もし `clientManifest` が提供されたら、返ってきたストリングはwebpackが放出したCSSファイルの``タグも含みます。 (例 : `extract-text-webpack-plugin`から抽出されたCSSや、`file-loader`でインポートされたCSS) + +- `context.renderState(options?: Object)` + + このメソッドは `context.state` をシリアライズし、 `window.__INITIAL_STATE__`ステートとして埋め込まれたインラインスクリプトを返します。 + +contextのステートキーとwindowのステートキーはどちらとも、オプションオブジェクトとして渡すことでカスタマイズできます。 + +```js + context.renderState({ + contextKey: 'myCustomState', + windowKey: '__MY_STATE__' + }) + // -> +``` + +- `context.renderScripts()` + - 必須 `clientManifest` + +このメソッドはクライアントアプリケーションを起動するのに必要な ` ` タグを返します。コードの中に非同期コード分割を使っている時、このメソッドは賢くも、インクルードされるべき正しい非同期チャンクを察します。 + +- `context.renderResourceHints()` + - 必須 `clientManifest` + +このメソッドは、今レンダーされているページに必要な`` リソースヒントを返します。 デフォルト設定このようになります: + +- ページに必要なJavaScriptやCSSファイルをプリロードする +- あとで必要な非同期JavaScriptチャンクをプリフェッチする + + ファイルのプリロードは[`shouldPreload`](./api.md#shouldpreload) オプションによってさらにカスタマイズが可能です。 + +- `context.getPreloadFiles()` + - 必須 `clientManifest` + +このメソッドはストリングを返さない代わりに、プリロードされるべきアセットを表すファイルオブジェクトの配列を返します。これは HTTP/2サーバプッシュをプログラムで行うときに使えるでしょう。 + +`createBundleRenderer`に渡された`template`は`context`を使って挿入されるので、これらのメソッドをテンプレート内で(`inject: false`で)使用することができます: + +```html + + + + {{{ renderResourceHints() }}} + {{{ renderStyles() }}} + + + + {{{ renderState() }}} + {{{ renderScripts() }}} + + +``` + +もし `template` を全く使っていないのなら、自分自身でストリングを結合することができます。 From 988a966df14b3be3b5b1626bf3751596c4563186 Mon Sep 17 00:00:00 2001 From: Sota Yamashtia Date: Tue, 30 May 2017 14:40:29 +0900 Subject: [PATCH 2/3] Translate build-config.md via GitLocalize From 53d5fc17307ac89d9a48203c12377e88286a1723 Mon Sep 17 00:00:00 2001 From: Hisako Shirasaki Date: Tue, 6 Jun 2017 20:50:58 +0900 Subject: [PATCH 3/3] Translate build-config.md via GitLocalize --- ja/build-config.md | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/ja/build-config.md b/ja/build-config.md index 8ce73b5a..e5445436 100644 --- a/ja/build-config.md +++ b/ja/build-config.md @@ -1,10 +1,10 @@ # ビルド設定 -クライアントサイドで完結するプロジェクトのwebpack設定は既に知っての通りでしょう。 SSRプロジェクトにおいても大枠は似たようなものですが、設定ファイルを3つのファイル( *ベース*、 *クライアント* 、 *サーバ* )に分けることを提案しています。 ベース設定は出力パス、エイリアス、ローダーのような両方の環境(TO DO：どれとどれ?)に共有される設定を含み、サーバ設定とクライアント設定は単純に、 [webpack-merge](https://github.com/survivejs/webpack-merge)を使って、ベース設定を拡張することができるものです。 +クライアントサイドで完結するプロジェクトのwebpack設定は既に知っての通りでしょう。 SSRプロジェクトにおいても大枠は似たようなものですが、設定ファイルを3つのファイル(*base*,*client*,*server*)に分けることを提案しています。base設定は出力パス、エイリアス、ローダーのような、clientとserver両方の環境に共有される設定を含み、server設定とclient設定は単純に、 [webpack-merge](https://github.com/survivejs/webpack-merge)を使って、base設定を拡張することができるものです。 -## サーバ設定 +## server設定 -サーバ設定は`createBundleRenderer`に渡されるサーババンドルを生成するために作られるもので、次のようになります: +server設定は`createBundleRenderer`に渡されるサーババンドルを生成するために作られるもので、次のようになります: ```js const merge = require('webpack-merge') @@ -43,7 +43,7 @@ module.exports = merge(baseConfig, { }) ``` - `vue-ssr-server-bundle.json`が生成されたら、ファイルパスを `createBundleRenderer`に渡すだけです: + `vue-ssr-server-bundle.json`が生成されたら、ファイルパスを `createBundleRenderer`に渡します: ```js const { createBundleRenderer } = require('vue-server-renderer') @@ -52,30 +52,30 @@ const renderer = createBundleRenderer('/path/to/vue-ssr-server-bundle.json', { }) ``` -別の方法として、 バンドルをオブジェクトとして`createBundleRenderer`に渡すことも可能で、これはホットリロード開発中に有効です。 参考として [HackerNewsの設定](https://github.com/vuejs/vue-hackernews-2.0/blob/master/build/setup-dev-server.js) を見てみてください。 +別の方法として、 バンドルをオブジェクトとして`createBundleRenderer`に渡すことも可能で、これは開発中のホットリロードに対して便利です。 参考として [HackerNewsの設定](https://github.com/vuejs/vue-hackernews-2.0/blob/master/build/setup-dev-server.js) を見てみてください。 -### 外部警告 +### externalsの注意 - CSSファイルを`externals`オプションにホワイトリスト登録していることに注目してください。その理由は、依存関係からインポートされるCSS はwebpackによって管理されないといけないからです。 もし同じようにwebpackに依存する他のタイプのファイルをインポートしているなら、 (例： `*.vue`, `*.sass`)、 それらも同じようにホワイトリストに加えなければいけません。 + CSSファイルを`externals`オプションにホワイトリスト登録していることに注目してください。その理由は、依存関係からインポートされるCSS はwebpackによって処理されないといけないからです。 もし同じようにwebpackに依存する他のタイプのファイルをインポートしているなら、 (例： `*.vue`, `*.sass`)、 それらも同じようにホワイトリストに加えなければいけません。 -ホワイトリスト登録する他のタイプのモジュールは、例えば `babel-polyfill`のような`global`を修正するポリフィルです。なぜなら、サーババンドルの中のコードは独自の ** `global` **オブジェクトを持っているからです。Node 7.6+を使っていればサーバに`babel-polyfill`はあまり必要ないので、単純にクライアントエントリーにインポートする方が簡単です。 +ホワイトリスト登録する他のタイプのモジュールは、例えば `babel-polyfill`のような`global`を修正するポリフィルです。なぜなら、サーババンドルの中のコードは独自の ** `global` **オブジェクトを持っているからです。Node7.6以降を使っていればサーバに`babel-polyfill`はあまり必要ないので、単純にクライアントエントリーにインポートする方が簡単です。 -## クライアント設定 +## client設定 -クライアント設定はベース設定とほぼ同じままです。言うまでもなく、クライアント側のエントリーファイルに`entry`を示す必要があります。またそれとは別に、もし`CommonsChunkPlugin`使っていたら、それがクライアント設定だけで使われていることを確認しておかないといけません。なぜなら、サーババンドルは単一のエントリーチャンクを要求するからです。 +client設定はbase設定とほぼ同じままです。言うまでもなく、クライアント側のエントリーファイルに`entry`を示す必要があります。またそれとは別に、もし`CommonsChunkPlugin`使っていたら、それがclient設定だけで使われていることを確認しておかないといけません。なぜなら、サーババンドルは単一のエントリーチャンクを要求するからです。 ### `clientManifest` の作成 -> 必須 version 2.3.0+ +> 必須 version 2.3.0以降 -サーババンドルに加えて、クライアントビルドマニフェストを作成することもできます。レンダラーは、クライアントマニフェストとサーババンドルでサーバ 側*と*クライアント側の両方のビルド情報を持つことになり、 レンダーされたHTMLに[preload / prefetch directives](https://css-tricks.com/prefetching-preloading-prebrowsing/)やCSSのlinkやscriptタグを自動的に挿入することができます。 +サーババンドルに加えて、クライアントビルドマニフェストを作成することもできます。レンダラーは、クライアントマニフェストとサーババンドルでサーバ側*と*クライアント側の両方のビルド情報を持つことになり、 レンダリングされたHTMLに[preload / prefetch directives](https://css-tricks.com/prefetching-preloading-prebrowsing/)やCSSのlinkやscriptタグを自動的に挿入することができます。 これには2重の恩恵があります: -1. 生成されたファイル名にハッシュがある時に、正しいURLをセットする`html-webpack-plugin` の代替になります。 -2. webpackのオンデマンドコード分割機能を利用するバンドルをレンダリングする時に、最適なチャンクがpreloaded / prefetchedされるのを保証でき、かつ、クライアントに対するウォーターフォールリクエストを避けるために、必要な非同期チャンクに``タグを挿入することができます。そのようにしてTTI (time-to-interactive)が改善します。 +1. 生成されたファイル名にハッシュがある時に、正しいURLを注入する`html-webpack-plugin` の代替になります。 +2. webpackのオンデマンドコード分割機能(code spliting)を利用するバンドルをレンダリングする時に、最適なチャンクがpreloaded / prefetchedされるのを保証でき、かつ、クライアントに対するウォーターフォールリクエストを避けるために、必要な非同期チャンクに``タグを挿入することができます。そのようにしてTTI (time-to-interactive)が改善します。 -クライアントマニフェストを利用するためには、クライアント設定はこのようになります： +クライアントマニフェストを利用するためには、client設定はこのようになります： ```js const webpack = require('webpack') @@ -138,13 +138,13 @@ const renderer = createBundleRenderer(serverBundle, { ### 手動でのアセットインジェクション -デフォルト設定で、アセットインジェクションはあなたが作成した`template`レンダーオプションで自動に行われます。 しかし、アセットがどのようにテンプレートにインジェクトされるかをより細かくコントロールしたい時もあるでしょうし、あるいはテンプレートを使わない時もあるかもしれません。そのような場合にはレンダラーを作る時に`inject: false`を渡せば、手動でアセットインジェクションを行うことができます。 +デフォルト設定で、アセットインジェクションはあなたが作成した`template`レンダリングオプションで自動に行われます。 しかし、アセットがどのようにテンプレートにインジェクトされるかをより細かくコントロールしたい時もあるでしょうし、あるいはテンプレートを使わない時もあるかもしれません。そのような場合にはレンダラーを作る時に`inject: false`を渡せば、手動でアセットインジェクションを行うことができます。 渡した`context`オブジェクトは`renderToString`コールバックで、 次のメソッドを持ちます: - `context.renderStyles()` -これは、レンダー中に使われた`*.vue`コンポーネントから集めた全てのクリティカルCSSを含んだ`` タグを返します。詳細は [CSS Management](./css.md)の章を見てください。 +これは、レンダリング中に使われた`*.vue`コンポーネントから集めた全てのクリティカルCSSを含んだ`` タグを返します。詳細は [CSS Management](./css.md)の章を見てください。 もし `clientManifest` が提供されたら、返ってきたストリングはwebpackが放出したCSSファイルの``タグも含みます。 (例 : `extract-text-webpack-plugin`から抽出されたCSSや、`file-loader`でインポートされたCSS) @@ -165,12 +165,12 @@ contextのステートキーとwindowのステートキーはどちらとも、 - `context.renderScripts()` - 必須 `clientManifest` -このメソッドはクライアントアプリケーションを起動するのに必要な ` ` タグを返します。コードの中に非同期コード分割を使っている時、このメソッドは賢くも、インクルードされるべき正しい非同期チャンクを察します。 +このメソッドはクライアントアプリケーションを起動するのに必要な `` タグを返します。コードの中に非同期コード分割を使っている時、このメソッドは賢くも、インクルードされるべき正しい非同期チャンクを推論します。 - `context.renderResourceHints()` - 必須 `clientManifest` -このメソッドは、今レンダーされているページに必要な`` リソースヒントを返します。 デフォルト設定このようになります: +このメソッドは、現在レンダリングされているページに必要な`` リソースヒントを返します。 デフォルト設定ではこのようになります: - ページに必要なJavaScriptやCSSファイルをプリロードする - あとで必要な非同期JavaScriptチャンクをプリフェッチする @@ -180,7 +180,7 @@ contextのステートキーとwindowのステートキーはどちらとも、 - `context.getPreloadFiles()` - 必須 `clientManifest` -このメソッドはストリングを返さない代わりに、プリロードされるべきアセットを表すファイルオブジェクトの配列を返します。これは HTTP/2サーバプッシュをプログラムで行うときに使えるでしょう。 +このメソッドは stringを返さない代わりに、プリロードされるべきアセットを表すファイルオブジェクトの配列を返します。これは HTTP/2サーバプッシュをプログラムで行うときに使えるでしょう。 `createBundleRenderer`に渡された`template`は`context`を使って挿入されるので、これらのメソッドをテンプレート内で(`inject: false`で)使用することができます: @@ -199,4 +199,4 @@ contextのステートキーとwindowのステートキーはどちらとも、 ``` -もし `template` を全く使っていないのなら、自分自身でストリングを結合することができます。 +もし `template` を全く使っていないのなら、自分自身でstringを結合することができます。